APIを利用するときに、クライアントはサーバーに送信するリクエストは、リクエストヘッダー、ボディ、及びクエリパラメータを利用してデータを渡しています。本文では、APIリクエストヘッダーを完全に解説する為に、APIリクエストヘッダーとは何かを解説した上、その書き方も皆さんに詳しく紹介します。
APIリクエストヘッダーとは
APIリクエストヘッダーとは、APIを呼び出すためのリクエストのヘッダー情報のことです。APIを利用するとき、クライアントはサーバーにリクエストを送信します。そのリクエストは、クエリパラメータ、ヘッダー、ボディなどの部分を使用してデータをサーバーに渡します。その中で、リクエストヘッダーは、そのリクエストの詳細情報をサーバー側に伝えるためのものです。
APIリクエストヘッダーはどのようなデータを渡す？
APIを利用するときには、目的のAPIで必要としているヘッダーをリクエストに含める必要があります。APIリクエストヘッダーは、主に以下のようなデータをサーバー側に渡すことができます。
クライアントの情報
- User-Agent - クライアントのソフトウェア名やバージョン
- Accept-Language - クライアントの使用言語設定
リクエストのメタデータ
- Content-Type - リクエストボディのデータ形式
- Content-Length - リクエストボディの長さ
認証/認可情報
- Authorization - 認証トークンやAPIキー等
- Cookie - セッション管理に使用するCookie
APIの指定
- Accept - 受け入れ可能なレスポンスのデータ形式
- API-Version - 使用したいAPIのバージョン
その他
- Cache-Control - キャッシュ指示
- If-Modified-Since - 最終更新日時の指定
これらのヘッダーを設定することで、サーバー側ではクライアントの状況を判断し、適切にレスポンスを返すことができます。リクエスト時に必要な情報を渡すための役割がヘッダーです。
リクエストヘッダーとボディの違いは？
APIリクエストにおけるヘッダーとボディも非常に多く利用されるものになっています。それでは、リクエストヘッダーとボディとの違いは何ですか？それぞれ渡すデータも違っていますか？次は、APIリクエストにおけるヘッダーとボディの違いを皆さんに紹介します。
定義の違い
ヘッダーはリクエストのメタデータを含む部分で、リクエストの内容や形式、認証情報などを指定するものになる一方、ボディはリクエストの本文の部分でPOSTなどのリクエストで実際に送信するデータ本体を含むものになります。
データフォーマットの違い
ヘッダーは、キーと値（Key-Value）のペアというデータ形式でデータをサーバーに渡していますが、ボディは、JSON等の構造化データを利用してデータを渡しています。
送信データの違い
ヘッダーは、認証情報等の制御データを送信する為に利用される一方、ボディは実データを送信する為に利用されることが多く見られます。
含まれるデータ量の違い
ヘッダーとボディに含まれるデータ量も違っています。ヘッダーには、非常に限定なデータのみを含めますが、ボディは実データを送信するため、比較的に大きなデータを送信することが可能です。
再利用性の違い
ヘッダーは、リクエスト間で共通しているので、再利用性がボディより高くなっています。その一方で、ボディはAPIによって異なるため、リクエストの間で共通なボディを利用できません。
上記のように、APIリクエストヘッダーとボディとの相違点を理解した上、それぞれの目的に合わせて適切なデータを記述することが重要です。
APIリクエストヘッダーの書き方
それでは、APIリクエストヘッダーにデータを追加して送信したい場合、APIリクエストヘッダーをどのように書きますか？
APIリクエストヘッダーは一般的にHTTPメソッドとエンドポイントURLの後に、ボディの前に置きます。その書き方は以下のようになります。
- ヘッダー名と値はコロン(:)で区切る
- ヘッダー名は文字列で記述し、大文字小文字は区別しない
- 値にスペースが含まれる場合はクオテーション(")で囲む
- 改行はCR+LF(復帰と改行)で表す
- 複数のヘッダーは改行で区切って記述する
POST /api/v1/users HTTP/1.1
Host: example.com
Content-Type: application/json // ヘッダー
Authorization: Bearer xxx // ヘッダー
{
"name": "John Smith",
"age": 35
}
上記は、完全なAPIのサンプルコードになります。1行目がリクエストラインで、メソッド、パス、HTTPバージョンを指定していますが、2行目以降がヘッダーの部分になります。この例ではホストとコンテンツタイプ、認証情報がヘッダーによって指定されています。
APIリクエスト送信、Apidogが最高！
Apidogは、非常に使いやすいAPI管理ツールとして、APIリクエストを送信してレスポンスを取得する場合、再便利なツールだと思われています。Apidogを使うことで、直感的なUIで簡単にリクエストを送信できます。クエリパラメータ、ボディ、ヘッダーを利用する場合でも、直感的な画面で直接に記入することも可能です。また、取得したレスポンスがAPI仕様書に一致しているかどうかを自動的に検証してくれますので、非常に便利です。
