初めに
クエリパラメータは、APIパラメータの一種として、WebアプリケーションやAPIでデータを動的に操作する上で欠かせない重要な機能です。
この記事では、クエリパラメータの定義から具体的な書き方、活用事例まで詳しく解説しました。Webアプリケーションの開発を行うためには、クエリパラメータの使用方法をよく理解しておくことが不可欠です。
また、ApidogのようなAPIクライアントツールを使うことで、クエリパラメータをより簡単に扱うことができ、開発・テストにおいて非常に有用です。クエリパラメータの正しい使い方を理解した上で、Apidogを活用することをおすすめします。
APIでクエリパラメータとは
クエリパラメータとは、URLに含まれるキーと値のペアのことで、URLパラメータとして知られていることも多くあります。具体的には、URLの?以降にあるキーと値のペア形式で指定されるパラメータのことを指します。
例えば、以下のようなURLの場合:
http://example.com/search?keyword=AI&page=2
ここで、2つのクエリパラメータがあります：
- keyword=AI
- page=2
クエリパラメータは、サーバーに対して追加の情報を渡すために利用されます。この例の場合、検索キーワードと表示ページを指定するために、クエリパラメータを利用しています。クエリパラメータはGETリクエスト時に主に利用され、サーバー側のプログラムへ参照して処理に利用します。POSTリクエストの場合はフォームデータとして渡すのが一般的です。
クエリパラメータの主な利用シーン
クエリパラメータは、主にサーバーに追加の情報を渡すことで、リクエストの内容を特定化・カスタマイズすることが主な目的なので、以下のようなシーンで利用されます。
- 検索条件の指定
- ページングの実装
- ソート順や表示件数などのオプション指定
- 商品や記事などのIDによるデータ取得
- ユーザーのフィルタリング条件の渡し方
- A/Bテストのグループ分け
- アクセス解析での情報付加
このように、クエリパラメータは、検索、ソート、フィルタリング、データ取得など、様々な場面で活用できる便利な仕組みです。クエリパラメータを適切に定義することで、同じエンドポイントでもリクエスト内容を柔軟に変化させることができます。こうして、APIエンドポイントを増やさずにAPIの機能を拡張できるようになり、ウェブアプリケーションの機能をもそれに伴って拡張できるのでしょう。
APIのクエリパラメータの書き方
それでは、クエリパラメータを利用したい場合は、それをどう書きますか？次は、クエリパラメータの書き方を丁寧に解説いたします。
基本構造
クエリパラメータは以下の基本構造になります。
?パラメータ1=値1&パラメータ2=値2...
- ?の直後にパラメータを記述する
- パラメータ名と値は「=」でくっつける
- 複数のパラメータは「&」で区切る
書き方の例
例えば、検索サイトで「猫」という検索ワードで、「ペット」カテゴリの検索結果を取得し、その結果を昇順に並べて欲しい場合、クエリパラメータは、次のような書く必要があります。
必要なパラメータ
| パラメータ名 | 値 |
|---|---|
| keyword | 猫 |
| category | pet |
| sort | asc |
これを実際に記述すると以下のようになります。
?keyword=猫&category=pet&sort=asc
- keywordパラメータに「猫」を設定し、検索キーワードを「猫」に検索することを意味します。
- categoryパラメータに「pet」を設定し、検索カテゴリを「ペット」カテゴリに指定することを意味します。
- sortパラメータに「asc」を設定し、検索結果の並び順を昇順(asc)に並べるようにすることを意味します。
エンコード
値にスペースや特殊記号が含まれる場合は、エンコードが必要です。
例えばスペースを「%20」、「+」記号を「%2B」のように置き換えて記述します。
APIでクエリパラメータの活用事例
WebアプリケーションやAPIの開発と利用中に、クエリパラメータを活用しているケースがたくさんあります。例えば：
検索サイトの検索キーワードや絞り込み条件の指定
GET /search?keyword=cat&location=tokyo
この例は、検索サイトの検索APIのクエリパラメータの利用例ですね。GETメソッドで/searchエンドポイントにアクセスしています。
以下のように、クエリパラメータを2つ利用中：
- keyword=cat
- location=tokyo
keywordパラメータは、検索時のキーワードを指定するためのものです。この場合、「cat」で検索することを示しています。
locationパラメータは、検索対象の地域を指定するためのものです。tokyoが設定されているので、東京の結果のみを取得する条件が指定されています。
サーバー側では、これらのパラメータを利用して、「cat」で検索し、かつ検索対象を東京のデータに限定する、という処理を行うことができます。
ECサイトの商品一覧での並び順や表示件数の指定
GET /products?sort=price&per_page=30
この例はECサイトの商品一覧APIのクエリパラメータの利用例です。GET メソッドで /products エンドポイントにアクセスしています。
クエリパラメータも２つ：
- sort=price
- per_page=30
sortパラメータは商品の並び順を指定するもので、priceの場合は価格順に並べるという指定になります。
per_pageパラメータは1ページ当たりの最大商品数を指定するもので、この場合は30件まで返すように指定されています。
サーバー側では、これらのパラメータに基づき、商品データを価格の低い順に並び替えて、30件まで切り取ったデータを返却する、といった処理が可能です。
SNSの投稿取得でのページングの実装
GET /posts?page=2&per_page=10
この例は、SNSの投稿を取得するAPIにおける、ページングを実現するためのクエリパラメータの例です。GETメソッドで /posts エンドポイントにアクセスしています。
クエリパラメータは次の2つ：
- page=2
- per_page=10
pageパラメータは取得したいページ番号を指定します。ここでは2ページ目のデータが欲しいことを示しています。
per_pageパラメータは1ページ当たりの最大取得投稿数を指定します。ここでは10件までを取得するように指定されています。
サーバー側では、これらのパラメータから、2番目のページ(11番目から20番目)の投稿データ10件を切り出して返却する、という処理が可能になります。
ユーザプロフィルの取得での個人情報フィルタリング
GET /user/123?fields=name,address
この例は、ユーザープロフィールを取得するAPIにおいて、取得するフィールドを指定するためにクエリパラメータを利用している例です。GETメソッドで /user/123 エンドポイントにアクセスしています。
これはユーザーIDが123のユーザー情報を取得するためのエンドポイントです。クエリパラメータとしてfields=name,addressが指定されています。
サーバー側では、このユーザーのレコードからname（名前）とaddress（住所）の値だけを抜き出して返却できます。
記事取得APIでの特定記事指定
GET /articles/123
この例は、記事取得APIにおいて、取得したい記事のIDをクエリパラメータで指定している例です。GETメソッドで /articles/123 エンドポイントにアクセスしています。
ここで123は、取得したい記事の記事IDを表しています。
このようにして、サーバー側では、この123というIDから、対応する記事データをDBなどから検索し、返却することができます。
A/Bテストでのバリエーション指定
GET /page?variation=A
この例は、A/Bテストを実施するウェブページにおいて、表示するバリエーションを指定するためにクエリパラメータを利用している例です。GETメソッドで /page エンドポイントにアクセスしています。
クエリパラメータとして、variation=A が指定されています。
このvariationパラメータは、どのバリエーションを表示するかを選択するためのものです。ここではバリエーションAを表示するよう指定されているので、サーバー側では、このパラメータから、リクエストしてきたユーザーにはAのバリエーションを返す、という処理が可能です。
APIでクエリパラメータを指定してサーバー送信する方法
それでは、実際にクエリパラメータをサーバー側に送信したい場合は、どうしたらいいですか？APIクライアントツールを使用して、サーバーにクエリパラメータを送信するのが一般的です。次は、一番使いやすいAPIクライアントのApidogを使用して、クエリパラメータを指定してサーバーに送信する方法を紹介します。
Apidogの直感的なUIで、APIのエンドポイントを記入して「送信」ボタンをクリックするだけで、リクエストを送信して、レスポンスを取得できます。
例えば、GETリクエストを送信する場合、URLを記入するだけで、URLに含まれるクエリパラメータとパスパラメータが自動的に抽出され、下のパラメータ欄に記入されるので、非常に便利です。例えば：
GET https://example.com/search?keyword=cat&sort=asc&num=30
をURLボックスに記入すると、keyword、sort、numといった3つのクエリパラメータは自動的に下記のQueryパラメータ欄に抽出できます。そして、このリクエストをAPIとして保存することもでき、今後このリクエストを再利用する必要があっても、直接に利用可能です。
終わりに
以上、クエリパラメータの定義から具体的な書き方、そして活用事例まで詳しく解説しました。Webアプリケーション開発を行うために、クエリパラメータの使い方をよく理解しておくことが不可欠だと言えるでしょう。
また、クエリパラメータを実際にサーバーに送信するには、ApidogのようなAPIクライアントツールが便利です。Apidogを使えば、URLにクエリパラメータを簡単に指定してリクエストを送信できます。また、パラメータの定義や値の入力もGUI上で直感的に行うことができます。APIの開発・テストにおいて、Apidogはクエリパラメータを扱う上でとても有用なツールだと言えます。クエリパラメータの正しい使い方を理解した上で、Apidogを活用することをおすすめします。
今回は以上になります！
最後まで見ていただきありがとうございました！
では、また次の記事で～！