API 設計ガイド

はじめに

これは、ネットワーク API の一般的な設計ガイドです。2014 年以来 Google 内部で使用され、Cloud API やその他の Google API を設計するときに Google が従うガイドです。この設計ガイドは、外部のデベロッパーへの情報提供と、互いの連携作業の効率化のためにここで共有されています。

Cloud Endpoints のデベロッパーには、このガイドは、gRPC API を設計するときに特に役立つことがあり、そのような場合にはこれらの設計原則を使用することを強くおすすめします。ただし、このガイドの使用は必須ではありません。Cloud Endpoints と gRPC はガイドに従わなくても使用できます。

このガイドは、gRPC API を中心に、REST API と RPC API の両方に適用されます。gRPC API では、プロトコルバッファを使用して API サーフェスを定義し、API サービス構成を使用して API サービス（HTTP マッピング、ロギング、モニタリングなど）を構成します。HTTP マッピング機能は、Google API と Cloud Endpoints gRPC API によって JSON / HTTP からプロトコルバッファ / RPC へのコード変換に使用されます。

このガイドは随時更新されるドキュメントで、今後も新しいスタイルや設計パターンの採用と承認に伴い、追加が発生します。このような考えから、このガイドは完成することはなく、常に、API 設計の技術の進歩を反映することができます。

このガイドで使用されている表記規則

必要レベルのキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119 に記載されているように解釈します。

このドキュメントでは、そのようなキーワードは太字で強調表示されています。

セクション

リソース指向の設計