HTTP ガイドライン

このドキュメントでは、さまざまな HTTP バージョンと実装での Google API の動作について説明します。生成済みか手動で作成されたクライアントライブラリのいずれかを使用している場合（ほとんどの使用例で推奨されるアプローチ）、サーバーとの通信に関する下位レベルの問題についてコード詳細が提供されるため、このことを考慮する必要はありません。

ただし、経験豊富なデベロッパーが、選択したサードパーティの HTTP クライアントライブラリを使用して API の REST インターフェースに直接アクセスして独自のカスタムコードを記述する必要がある場合は、ここにドキュメント化されているセマンティクスのうち（選択した API への関連性に応じて）少なくとも一部を理解すると同時に、使用する HTTP ライブラリの内容を理解している必要があります。

ワイヤプロトコル（HTTP/*）の使用

ここでは、Cloud API でクライアントとサーバーの間の通信に使用できる、サポートされているワイヤプロトコル（通常は HTTP のバージョン）と、推奨されるこれらの使用方法について説明します。リクエストとレスポンスの構造の詳細については、次のセクションで説明します。

HTTP セマンティクス

API クライアントコードを開発する場合は、標準の HTTP プロトコルセマンティクスに従います。サーバー側のプロキシや API スタックでは、標準の HTTP 機能のサブセットのみがサポートされる場合がありますが、下位互換性のあるバージョンがサポートされる場合もあります。

API のサーバー側実装によって処理する必要がある HTTP プロトコルのセマンティクスは、サーバースタックによって制御されます。これらの機能が API 仕様の一部（キャッシュサポートなど）として明示的にドキュメント化されている場合にのみ、このようなセマンティクスに依存するようにしてください。

HTTP バージョン

クライアントでは、クライアントプラットフォームやクライアント側のネットワークで許可されるか、サーバー側のプロキシでネゴシエートされるすべての HTTP/* プロトコルを使用できます。サポートされているプロトコルには、HTTP/1.0、HTTP/1.1、SPDY/*、HTTP/2、QUIC があります。

サーバーの push や優先度などの一部の API 機能は、新しいバージョンの HTTP プロトコルでのみサポートされる場合があります。また、全二重のストリーミングなど、HTTP/2 でのみ完全に指定されているものもあります。API 仕様の一部としてこれらの機能のいずれかが必要な場合は、異なる HTTP バージョンの制限に注意してください。

通常、パフォーマンスとネットワーク障害に対する復元力の高さから、HTTP/2 が推奨されます。

チャネル

チャンネルは、L4 ネットワーク接続（TCP ソケットや UDP ソケット）を指します。HTTP リクエストを処理するときにランタイムでチャネルがどのように使用されるかについて、クライアントアプリケーションではいかなる想定もしない必要があります。ほとんどの場合、チャネルはサーバープロセスの代わりにプロキシによって終了されます。

HTTP/1.1 クライアントの場合は、常に TCP 接続（接続: キープアライブ）を再利用してください。パフォーマンス向上のために、HTTP クライアントライブラリによって接続プールも管理されると考えられます。同じ TCP 接続を介してリクエストをパイプライン化しないでください。詳細については、HTTP と TCP をご覧ください。

最新のブラウザはすべて、SPDY/* や HTTP/2、QUIC に対応することで、単一のチャネルを介してリクエストを多重化しています。従来の接続制限（2～10）は、サーバーの実装により単一のクライアントからの同時 HTTP リクエスト数が抑制される場合（単一の送信元に対して HTTP/2 ストリームが 100 個に制限される場合など）を除き、考慮する必要はありません。

HTTPS

クライアントは、API 仕様でサポートされているように、HTTPS または HTTP 経由で API にアクセスできます。TLS ネゴシエーションと TLS バージョンはクライアントアプリケーションに対して透過的です。デフォルトでは、Google API では HTTPS トラフィックのみが許可されます。

リクエスト / レスポンスの形式

リクエスト URL

JSON-REST マッピングでは、URL エンコードされたリクエストデータがサポートされ、HTTP リクエストとレスポンスの本文では Content-Type として application/json が使用されます。

HTTP 本文では、ストリーミングされた RPC メソッドが JSON 配列を使用してサポートされ、JSON 配列には、任意の数の JSON メッセージやエラーステータスの JSON メッセージを含めることができます。

長いリクエスト URL

URL には実用的な長さ制限があり、通常は 2 k～8 k です。この制限は、一部のブラウザとプロキシによって強制されます。API で長さ制限を超える URL を含む GET リクエストを使用する場合、このようなリクエストはブラウザによって拒否される可能性があります。この制限を回避するには、クライアントコードで、Content-Type が application/x-www-form-urlencoded で、HTTP ヘッダーが X-HTTP-Method-Override: GET の POST リクエストを使用する必要があります。この方法は、DELETE リクエストに対しても有効です。

HTTP メソッド（動詞）

リクエスト URL が REST モデルに従う場合、その HTTP メソッドは API 仕様の一部として指定されます。特に、すべての API メソッドは、その API メソッドがマッピングされる特定の HTTP 動詞に基づいて、HTTP プロトコルの要件に準拠している必要があります。詳細については、ハイパーテキスト転送プロトコルの仕様と PATCH メソッドの RFC をご覧ください。

HTTP GET や HEAD などの安全なメソッドで、取得以外の操作を表すことはできません。特に、HTTP GET は安全であると考えられているため、クライアントが認識できる副次的影響が発生しないようにしてください。

HTTP のべき等性とは、複数の同一のリクエストの副作用が単一のリクエストの場合と同じであることを意味します。GET、PUT、DELETE は、スタイルガイドに関連するべき等 HTTP メソッドです。べき等性は、サーバーの副作用という観点でのみ示され、レスポンスについては一切指定しないことに注意してください。特に、存在しないリソースの DELETE では、404 (Not Found) が返されることが推奨されます。

HTTP POST と PATCH は安全でもべき等でもありません（PATCH は RFC 5789 で導入されました）

HTTP 動詞	安全	べき等
`GET`	○	○
`PUT`		○
`DELETE`		○
`POST`
`PATCH`

ペイロード形式

リクエストとレスポンスは、リクエストが本文に application/x-www-form-urlencoded を持つ GET か POST の場合を除き、同じ Content-Type を共有する必要があります。
JSON は、application/json MIME タイプでサポートされています。proto3 から JSON へのマッピングは、JSON マッピングで正式に指定されています。
リクエストフィールドをクエリパラメータにマッピングする場合と同じ REST スタイルのマッピングルールに従って、URL クエリパラメータ（GET）の代わりにフォームパラメータ（POST）を使用できます。サポートされている Content-Type は application/x-www-form-urlencoded です。

ストリーミング

半二重と全二重

HTTP は、リクエストやレスポンスの本文を TCP（HTTP/1.x）やその多重化されたバリアント（SPDY、HTTP/2、QUIC）などのさまざまなストリーム指向トランスポートを介して配信できるようにする、リクエストとレスポンスのプロトコルです。

クライアントデベロッパーは、アプリケーションを使用して、リクエスト本文をストリーミングモード（クライアントストリーミング）で生成できます。同様に、アプリケーションがストリーミングモード（サーバーストリーミング）でレスポンス本文を使用することもできます。

ただし、HTTP 仕様では、リクエスト本文がまだ保留中の場合に、サーバーによるレスポンス本文（エラーレスポンスを除く）のストリーミングバックを許可するかどうかは指定されません。このセマンティックは、全二重ストリーミングと呼ばれます。多くの HTTP クライアント / サーバー / プロキシソフトウェアでは、HTTP/1.1 についても全二重ストリーミングを行うことができますが、相互運用性に関する問題を回避するために、HTTP ベースの Cloud API は半二重ストリーミングのみに制限されます。

デフォルトでは、Cloud API の Bidi ストリーミングメソッドは全二重セマンティクスを前提としています。つまり、HTTP を使用してこのようなメソッドを呼び出すのは安全ではありません。ストリーミングメソッドが半二重のみである場合（サーバーによって適用される場合）、API ドキュメントで半二重動作を明確に指定する必要があります。

ブラウザクライアントの場合、標準の HTTP セマンティクスは、ブラウザの Network API によってさらに制約を受けます。現在のところ、ブラウザは XHR または Fetch 経由の（通常はトランスポートレベルのフレーム処理が考慮される）サーバーストリーミングのみがサポートされています。Fetch API は whatwg ストリームを使用します。

ブラウザの制限により、ブラウザのサポートを必要とする Cloud API は、クライアントストリーミングと全二重ストリーミングを避けるか、ブラウザクライアント専用の個別 API を提供する必要があります。

通常、インターネットを介したクライアントストリーミングは、サーバーストリーミングほど有益ではありません。これは、クライアントストリーミングを使用すると、多くの場合、ステートフルなサービスが発生して負荷分散に悪影響を及ぼし、システムが障害や攻撃に対してより脆弱になるためです。一方、サーバーストリーミングは、RTT の遅延が長いネットワークのレイテンシを大幅に削減できるので便利です。

メッセージエンコード

ストリーミング時の JSON メッセージは、JSON メッセージの配列としてエンコードされます。リクエストやレスポンスの本文は、有効な JSON MIME タイプのままとなります。

クライアントストリームのエンコードの例:

1 <length> <message-bytes> 1 <length> <message-bytes>  … EOF

サーバーストリームのエンコードの例:

1 <length> <message-bytes>  … 2 <length> <status-bytes> EOF

ワイヤレベルのエンコード: StreamBody の定義は、タグ ID の割り当てにおいてのみ重要となります。これは、フィールド「messages」と「status」は、通常のメッセージでは 1～2 バイトでエンコードされるバリアントとなり、合計エンコードのオーバーヘッドはメッセージあたり 2～3 バイトになるためです。

base64 エンコードストリームをサポートするには、オプションのパディングフィールドが必要です。

message StreamBody {
  repeated bytes message = 1;
  google.rpc.Status status = 2;
  repeated bytes padding = 15;   // max one-byte tag-id: xxx01111
}

エラーメッセージは、通常のメッセージと同じ形式で、JSON 配列や protobuf 配列の最後の要素として追加してください。

状態管理

ハーフクローズ動作はすべての HTTP バージョンで明確に定義され、クライアントやサーバーは、本文が完了したことを他方の側にシグナルとして送信できます。

具体的には、クライアントコードでは、レスポンスの待機中でも、リクエストを自由に完了できます。同様に、クライアントでは、リクエスト本文がサーバーに書き込まれている途中でも、完了したレスポンスを表示できます。HTTP 標準では、レスポンスが予期しない方法で完了した（通常はエラーステータスを伴って）場合、クライアントによってリクエストが中止されるか完了されることが想定されています。つまり、通常の条件下では、クライアントからリクエストが送信されている途中に、サーバーによってレスポンスが完了されることはありません。

キャンセル

キャンセルサポートにより、リクエストやレスポンスの保留中に、クライアントでリクエストを中止できます。

リクエスト / レスポンストランザクションを中断せずに、リクエストが完了した後にクライアントで TCP 接続を自由に閉じることができるため、HTTP/1.* クライアントには信頼性の高いキャンセルサポートは存在しません。接続がキープアライブ（接続: キープアライブ）としてマークされている場合でも、HTTP/1.1 での TCP FIN をキャンセルとして解釈しないでください。

ただし、クライアントが TCP 接続を閉じた後、サーバーがなんらかのデータをクライアントに書き込むことを試みると、RST が生成されてキャンセルがトリガーされることがあります。

また、キャンセルは非ストリーミング API でも問題となるので注意してください。このことは、特に、レスポンスによって長時間のポーリングが発生し、接続が長期間アイドル状態になる可能性がある場合に当てはまります。

明示的なキャンセルは、特に、切断メッセージについて SPDY、HTTP/2、QUIC でサポートされています。

キープアライブ

キープアライブサポートにより、クライアントやサーバーでは、パケット損失やネットワーク障害が発生した場合でも、障害が発生したピアを検出できます。

TCP キープアライブは実現可能なアプローチではないため、HTTP/1.1 にキープアライブサポートは存在しません。

QUIC や HTTP/2 では、ブラウザなどのアプリケーションによってキープアライブサポートを実装する目的で、特別な制御メッセージが提供されています。

ただし、信頼性の高いキープアライブと障害検出には、サーバー側のサポートを必要とするクライアントライブラリが必要となる可能性があります。通信プロトコルとして基本 HTTP に依存する場合、インターネットを介して長時間ストリーミングを行うと、通常はエラーが発生しやすくなります。

フロー制御

フロー制御サポートでは、クライアントにより、トランスポートレベルのフロー制御イベントをクライアントアプリケーションに伝播する必要があります。実際のメカニズムは、クライアントアプリケーションで使用する HTTP クライアント API のスタイルに依存します。たとえば、クライアントやサーバーの過負荷を防ぐために、アプリケーションによりフロー制御イベントを処理して考慮するには、明示的なフロー制御サポートを使用して、書き込みと読み取りをブロックしたり、ブロックを解除したりすることが必要となります。

HTTP/1.1 は、TCP フロー制御に依存します。

SPDY と HTTP/2 では、ストリームレベルで独自のフロー制御が行われます。この場合、リクエストが単一の TCP 接続を介して多重化されるため、さらに接続レベルで TCP フロー制御に依存します。

QUIC は UDP 上で動作するため、フロー制御は自動的に完全に管理されます。