時々、APIで同じクエリパラメータに複数値を渡す必要があります。APIでクエリパラメータを使用してデータを渡す場合は、常にキーと値のペア形式で簡単に指定することができますが、もし同じパラメータに値を複数指定する必要がある場合、どうしたらいいですか？本文では、APIのGETで同じパラメータに複数値を渡す方法を皆さんに紹介します。
使いやすいAPI管理ツールのApidogは、直感的なUIでコーディング不要で同じパラメータで複数値を渡すことができますので、下記のボタンからいち早く体験してみましょう：
同じパラメーターで複数値を渡したい！
近日、ネットで次のような質問を見ました。
「現在PHPサイトをメンテナンスしておりまして
件名の通り
GETで同じパラメーターで複数 値を渡したいと思っております。
チェックボックスにチェックがつく値です……
□羊羹
☑たい焼き
☑おはぎ
でURLにcheck=1がついているとたい焼きに☑がつくという実装をしたいと思っております。
つまり
http://www.hoge.com/seihin.php?check=1&check=2
たい焼きとおはぎに☑がつくようにしたいと思っております。
このような場合どのように渡すのが良いか伺ってよろしいでしょうか？
なんか実装していくうちにもっと良いやり方があるような気がしてきたのです……
お忙しい所大変申し訳無いのですが上記お問い合わせいたします。」
参照元：https://teratail.com/questions/148337
というように、APIをテストしたりする時に、同じクエリパラメータでも複数の値を渡す必要が時々あります。このような場合、どうしたらいいですか？次は、これを完全に実現できる対策を皆さんに紹介します。
なぜか同じパラメータで複数値を渡す必要がある？
この部分では、上記場合を含め、APIで同じパラメータで複数値を渡す必要がなぜあるのかを解説していきたいと思います。APIで同じパラメータに複数の値を渡す必要がある理由といえば、主に以下の通りです。
- パラメータが配列やリストを受け取る設計になっている場合。例えば、
users=[1,2,3]のように、ユーザーIDの配列を渡す場合など。 - OR条件でのフィルタリングを実現したい場合。例えば、
status=1&status=2のようにステータスが1または2のデータを検索する場合。 - API側で複数の値を区切る文字が決まっている場合。例えば、
tags=python,javascriptのようにカンマで区切る場合。 - 1つのパラメータに対して、複数の値を指定したい場合。例えば、
sort=name,-createdAtのように並び替え条件を複数指定する場合。 - リクエストボディではなくURLに指定したい場合。POSTのJSONデータよりも、GETのURLパラメータの方が扱いやすい場合がある。
このように、APIの仕様や用途に応じて、同じパラメータに複数の値を渡す必要性が生じることがあります。クライアント側はそのAPIの仕様を確認し、適切に複数の値を渡せるよう実装する必要があります。
同じパラメータで複数値を渡す方法
それでは、APIで同じパラメータに複数値を渡す必要がある場合、どうすればいいですか？この部分では、OpenAPI仕様によって規定された記述方法を紹介した上、Apidogという一番使いやすいAPI管理ツールを使って、同じパラメータで複数値を渡してリクエストを送信する方法を紹介します。
OpenAPI仕様に規定された記述方法
実際には、同じパラメータで複数値を渡す必要がある場合、OpenAPI仕様に従ってその記述方法は次のようになります：
| Style | Explode | URI template | Primitive value id = 5 | Array id = [3,4,5] |
|---|---|---|---|---|
| form * | true * | /users{?id*} | /users?id=5 | /users?id=3&id-4&id=5 |
| form | false | /users{?id} | /users?id=5 | /users?id=3,4,5 |
| spaceDelimited | true | /users{?id*} | n/a | /users?id=3&id-4&id=5 |
| spaceDelimited | false | n/a | n/a | /users?id=3%20id-4%20id=5 |
| pipeDelimited | true | /users{?id*} | n/a | /users?id=3&id-4&id=5 |
| pipeDelimited | false | n/a | n/a | /users?id=3|4|5 |
| deepObject | true | n/a | n/a | n/a |
上記テーブルの方法をまとめてみると、OpenAPI仕様に従って、同じパラメータで複数値を渡す記述方法は次になります：
- formスタイルでexplode=trueの場合: リクエスト例
/users?id=1&id=2&id=3 - spaceDelimitedスタイルでexplode=trueの場合: リクエスト例
/users?id=1&id=2&id=3 - pipeDelimitedスタイルでexplode=trueの場合: リクエスト例
/users?id=1&id=2&id=3 - formスタイルでexplode=falseの場合: リクエスト例
/users?id=1,2,3 - pipeDelimitedスタイルでexplode=falseの場合: リクエスト例
/users?id=1|2|3
要約すると、
- explode=trueの場合は、キーを繰り返し指定する
- explode=falseの場合は、カンマやパイプ記号などの区切り文字を使用する
ことで、同じパラメータに複数の値を渡すことができます。スタイルとexplodeの設定によって、リクエストフォーマットが異なる点に注意が必要です。
Apidogで同じパラメータで複数値を簡単に渡す
また、APIをテストしたりする時に、Apidogという非常に使いやすいAPI管理ツールを使ってこの作業を簡単に実現できます。Apidogは、APIの設計、API仕様書生成、テスト、モックサーバーなどの機能を備えており、APIをいつもより効率的に管理できる次世代のツールになります。
それでは、次のステップに従って、簡単に複数値を同じパラメータに追加して、リクエストを送信しましょう。
ステップ⒈Apidogを開いて新しいプロジェクトを作成すると、「＋」ボタンをクリックして、「新しいRequest」を選択することで、リクエストを新規に作成します。
ステップ⒉リクエストの画面で、APIエンドポイントのURLを入力して、クエリパラメータを記入します。
ご案内：エンドポイントのURLの?以降のキーと値のペア形式でクエリパラメータを指定します。同じパラメータで複数値を渡す必要がある場合、クエリパラメータを繰り返して指定してください。
ステップ⒊URLに記述しているクエリパラメータがQueryパラメータのエリアに抽出されるので、必要に応じて送信したいパラメータをチェックして、「送信」ボタンをクリックします。
Apidogはデフォルトとしてid=3&id=4&id=5というようにKeyと値のペアでパラメータ値を渡していますが、API仕様が他の渡し方を規定する場合、その仕様に従って同じパラメータで複数値を渡すことができます。
まとめ
APIで同じパラメータに複数の値を渡す必要がある場合は、OpenAPIの仕様に沿って、explodeフラグや区切り文字を使って実装する必要があります。ApidogはAPIの設計・ドキュメント作成・テスト・モックサーバーなど、APIの開発を効率的に行うことができるツールです。APIテスト時に同じパラメータに複数の値を簡単に渡すには、Apidogがおすすめです。
Apidogを利用することで、同じパラメータに複数の値を簡単に渡してリクエスト送信をテストできます。
