APIのデータ渡し方：パラメータを完全解説

APIはソフトウェアやプログラム、Webサービスの間をつなぐインターフェースのことでソフトウェア同士が情報をやり取りする際に使用されます。APIでデータを交換したり、データを渡したりするには、APIのパラメータを利用する必要があります。本文では、APIのパラメータについて詳しく解説した上、パラメータをつけたままリクエストを送信する方法も一緒に紹介します。

APIのパラメータとは

リクエストパラメータは、主にAPIのリクエスト送信の際に利用されるものになります。その役割は、クライアントとサーバーの間でデータを渡すことです。APIのリクエストを送信するとき、利用できるパラメータの種類が多くありますが、主に次のような種類があります。

クエリパラメータ

クエリパラメータは、GETリクエストのパラメータをURLに含めるのに利用されています。

ボディパラメータ

ボディパラメータは、POSTなどのリクエストボディにデータを含めるパラメータです。

ヘッダーパラメータ

リクエストヘッダやレスポンスヘッダに含むパラメータになり、Authorizationで認証情報を、Content-Typeで内容の形式などを指定するのに使われることが多くなります。

パスパラメータ

パスパラメータは、URLパスの一部を変数として利用するパラメータになり、URLでリソースを特定するのに使われるのが多くみられています。

APIでは目的に応じてこれらのパラメータを組み合わせて利用するのが一般的で、要件に応じて適切なパラメータを使い分けることが重要です。そこで、リクエストパラメータは、URLパラメータより広い概念で、APIリクエストを送信する時に利用されるパラメータの全般を指しています。

よく利用されるパラメータ（HTTPメソッド別）

APIが利用しているHTTPメソッドが異なる場合は、実際にデータを渡すために利用されるパラメータもずいぶん違っています。次は、各HTTPメソッドを採用しているAPIのリクエストを送信するために、よく利用するAPIパラメータの種類を皆さんに紹介します。

GETリクエストのパラメータ

GETリクエストでは主にURLパラメータであるクエリパラメータとパスパラメータが利用されます。クエリパラメータにkey=valueの形式で指定しますが、パスパラメータはURLの一部を利用してリソースを指定します。

例えば、 https://example.com/search?keyword=cat&limit=10 の場合、URLの?以降にkey=valueの形式で指定します。検索条件や絞り込みフィルターなどを指定するのに利用されます。また、/users/12345 の12345がパスパラメータになります。

POSTリクエストのパラメータ

POSTリクエストでは主にボディパラメータが利用されます。JSONやXML、フォームデータなどで入力値をボディに記述します。
例:POST /users/1234 { "name": "Tanaka", "age": 30 }というリクエストがあったとします。このリクエストは、ユーザーデータのコンテナである /users に新しいレコードの1234を追加するという操作を指示しています。また、リクエストボディに含まれる { "name": "Tanaka", "age": 30 } が、実際に追加する新しいレコードデータです。nameが"Tanaka"、ageが30の新規ユーザーデータを表しています。

PUTリクエストのパラメータ

PUTリクエストもボディパラメータを利用します。PUTはレコードの上書きが目的のため、URIパスには更新対象のIDが含まれます。

例: PUT /users/1234 { "name": "Suzuki" } というリクエストがあったとします。このリクエストは、ユーザーデータの中から、IDが1234のユーザー情報を探し出し、そのユーザーのnameを「Suzuki」に変更する、という操作を指示しています。

DELETEリクエストのパラメータ

DELETEリクエストは主にパスパラメータが利用されます。削除対象のリソースをURIパスで指定します。

例: DELETE /users/5678 というリクエストがあったとします。このリクエストは、ユーザーデータからIDが5678のレコードを削除するという操作を指示しています。 リクエストのURLに含まれる /users/5678 が、削除対象のデータを特定するためのパスパラメータです。

このように、APIの用途に応じて適切なパラメータを選択することが重要です。APIの仕様を確認して意図したデータを渡すことを心がけましょう。

ApidogはAPIパラメータ全般にもご対応

API送受信が必要となる場合は、Apidogという優れていたAPI管理ツールは一番簡単な対策だと思います。直感的なUIで、APIのエンドポイントを記入するだけで、リクエストを送信できます。Apidogは、GET、POST、PUT、DELETEなどのHTTPメソッドにも対応可能なので、どのようなリクエストを送信したい場合でも、Apidogはそれを完全に実現できます。

また、リクエスト送信時に利用可能なパラメータをも全てサポートできるので、クエリパラメータ、パスパラメータ、ボディパラメータ、ヘッダーパラメータなどを利用する必要がある場合、Apidogが提供してくれたビジュアルエディターで簡単に操作可能です！

Apidogでクエリパラメータとパスパラメータを利用

例えば、GETリクエストを送信する場合、URLを記入するだけで、URLに含まれるクエリパラメータとパスパラメータが自動的に抽出され、下のパラメータ欄に記入されるので、非常に便利です。例えば：

GET https://example.com/search?keyword=cat&sort=asc&num=30

をURLボックスに記入すると、keyword、sort、numといった3つのパラメータは自動的に下記のパラメータ欄に変換できます。そして、このリクエストをAPIとして保存することもでき、今後このリクエストを再利用する必要があっても、直接に利用可能です。

Apidogでボディパラメータの利用

また、POST、PUTなどのリクエストを送信する場合、「Body」タブに切り替えて、リクエストボディを利用することも可能です。

Apidogでヘッダパラメータを利用

さらに、User-Agent、Content-Type、または認証情報などを指定する場合、「Headers」タブに切り替えて簡単に指定できます。

まとめ

APIを扱う上で、リクエスト時のパラメータ設定は欠かせない作業となります。しかし、パラメータの種類や使い方は複雑で、正しく設定するのは大変です。

そんなとき、Apidogが問題を一掃してくれます。ApidogならGUIベースの操作で、さまざまなパラメータを直感的に設定できます。URLの入力だけで、クエリやパスパラメータが自動設定されるなど、手間のかからない操作性が魅力。さらに、ボディやヘッダーの設定も視覚的に支援してくれます。

API初心者にも優しいApidogを使えば、楽しみながらパラメータの意味を理解し、正しい設定ができるようになるはずです。ぜひ活用してみてください。