Web開発：リクエストパラメータとURLパラメータ

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つのクエリパラメータがつけられています：

1. keyword = cat
2. 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のようなツールを活用していくことをおすすめします。