Web開発の際、特にAPI送受信を行いたい場合、クライアントとサーバー間でデータを渡すために、リクエストパラメータが利用されています。本文では、リクエストパラメータの基本情報を詳しく紹介した上、皆さんによく利用されているURLパラメータの使い方をも一緒に解説してみたいと思います。
また、APIクライアントツールのApidogは、全種類のリクエストパラメータにも完璧に対応可能なので、APIを練習したりする必要がある場合、Apidogをぜひ試してください。
リクエストパラメータとは
リクエストパラメータは、主にAPIのリクエスト送信の際に利用されるものになります。その役割は、クライアントとサーバーの間でデータを渡すことです。APIのリクエストを送信するとき、利用できるパラメータの種類が多くありますが、主に次のような種類があります。
クエリパラメータ
クエリパラメータは、GETリクエストのパラメータをURLに含めるのに利用されています。クエリパラメータは実際、GETリクエストのURL内に含まれるものです。
https://example.com/api/users?page=2&sort=name
上記の例では、pageとsortがクエリパラメータとなっています。
ボディパラメータ
ボディパラメータは、POSTなどのリクエストボディにデータを含めるパラメータです。
{
"name": "John Doe",
"email": "john.doe@example.com"
}上記の例では、JSONフォーマットでユーザー情報がボディパラメータとして送信されています。
ヘッダーパラメータ
リクエストヘッダやレスポンスヘッダに含むパラメータになり、Authorizationで認証情報を、Content-Typeで内容の形式などを指定するのに使われることが多くなります。
Authorization: Bearer abc123xyz
Content-Type: application/json
上記の例では、AuthorizationとContent-Typeがヘッダーパラメータとなっています。
パスパラメータ
パスパラメータは、URLパスの一部を変数として利用するパラメータになり、URLでリソースを特定するのに使われるのが多くみられています。
https://example.com/api/users/123
上記の例では、123がユーザーIDのパスパラメータとなっています。
APIでは目的に応じてこれらのパラメータを組み合わせて利用するのが一般的で、要件に応じて適切なパラメータを使い分けることが重要です。そこで、リクエストパラメータは、URLパラメータより広い概念で、APIリクエストを送信する時に利用されるパラメータの全般を指しています。
よく言われる「URLパラメータ」とは？
それでは、皆さんによく利用されているURLパラメータとは何でしょうか？
URLパラメータは、その名前通りに、URLの中に含まれるパラメータのことになります。より正確的にいうと、皆さんによく言われる「URLパラメータ」は、実際に「クエリパラメータ」と「パスパラメータ」になります。
クエリパラメータもパスパラメータもエンドポイントのURLに含まれていますので、どのように使い話分けますか？次は、同じくURLパラメータとも言えるパスパラメータとクエリパラメータの概念を詳しく解説します。
クエリ（Query）パラメータ及びその使い方
クエリパラメータは、URLの中で疑問符(?)から始まる部分のパラメータのことを指します。
例えば以下のURLの場合、
http://example.com/search?keyword=cat&orderby=date
?符号以降のkeyword=cat&orderby=dateの部分がクエリパラメータです。そこで、以下の2つのクエリパラメータがつけられています：
- keyword = cat
- orderby = date
上記のように、クエリパラメータはKEY=VALUEの形（キーと値のペア）で指定し、複数のパラメータを追加する場合は、&符号で繋げて指定することができます。クエリパラメータはGETリクエスト時にデータを渡すために用いられます。サーバー側ではこれらのパラメータを解析して必要な処理を行います。
クエリパラメータはURLパラメータの一種で、GETリクエスト時にデータを渡すために利用されるものです。URLに含まれるパラメータの呼び方と理解してもOKです。
パス（Path）及びその使い方
Pathパラメータは、URLのパスの一部を変数として利用するためのパラメータです。
例えば、以下のようなURLがあったとします。
https://example.com/users/12345
ここで、usersの後ろの12345の部分をPathパラメータとして利用できます。
https://example.com/users/{id}
のように{}で囲まれるidを変数として扱えます。
この{id}の部分がPathパラメータです。
これにより、/users/12345、/users/5678などのように、同じURLパターンで異なるページを表示できます。
Pathパラメータは主に、次のようなシーンで利用されています。
- ユーザーページなどの個別のリソースにアクセスする時
- REST APIのエンドポイントでリソースを特定する時
URLのパスの一部分を変数化して柔軟なルーティングを実現するための仕組みだと理解してください。
Apidog：全てのリクエストパラメータも利用可能
API送受信が必要となる場合は、Apidogという優れていたAPI管理ツールは一番簡単な対策だと思います。直感的なUIで、APIのエンドポイントを記入するだけで、リクエストを送信できます。また、自分でAPIを開発する場合は、APIの設計だけではなく、APIの仕様書生成、テスト自動化、データモックなど、様々な機能もできます。
例えば、GETリクエストを送信する場合、URLを記入するだけで、URLに含まれるクエリパラメータとパスパラメータが自動的に抽出され、下のパラメータ欄に記入されるので、非常に便利です。例えば：
GET https://example.com/search?keyword=cat&sort=asc&num=30
をURLボックスに記入すると、keyword、sort、numといった3つのパラメータは自動的に下記のパラメータ欄に変換できます。そして、このリクエストをAPIとして保存することもでき、今後このリクエストを再利用する必要があっても、直接に利用可能です。
また、GETリクエストのほかに、POST、PUT、DELETEなどのリクエストにも完璧に対応できるので、ボディパラメータ、ヘッダパラメータなどの他のリクエストパラメータを利用して、データを渡したい場合は、Apidogもそれを簡単に実現できるので、APIをテストしたり、練習したりしてみたい方は、Apidogは最適なツールだと思います。
まとめ
この記事では、Web開発でAPIを利用する際に重要なリクエストパラメータとURLパラメータについて説明しました。リクエストパラメータには様々な種類があり、目的に応じて使い分ける必要があります。一方、URLパラメータはその一部に過ぎません。
APIを開発したりテストしたりするには、Apidogのようなツールが便利です。直感的なUIでリクエストが作成でき、パラメータも自動的に設定されます。ApidogではAPIのドキュメント作成やモックデータの生成など、API開発を支援する様々な機能があります。
パラメータの概念を理解した上で、実際の開発ではApidogのようなツールを活用していくことをおすすめします。
