はじめに
これは、ネットワーク 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 に記載されているように解釈します。
このドキュメントでは、そのようなキーワードは太字で強調表示されています。
セクション
リソース指向の設計
RPC API と REST API にリソース指向設計を実装する方法については、AIP-121 をご覧ください。
リソース名
リソース名については、AIP-122 をご覧ください。
標準メソッド
メソッドの一般的な情報については、AIP-130 をご覧ください。
標準メソッドの詳細については、次の AIP をご覧ください。
Getについては、AIP-131 をご覧ください。Listについては、AIP-132 をご覧ください。Createについては、AIP-133 をご覧ください。Updateについては、AIP-134 をご覧ください。Deleteについては、AIP-135 をご覧ください。
カスタム メソッド
カスタム メソッドの詳細については、AIP-136 をご覧ください。
その他のトピック
次のトピックについては、関連する AIP をご覧ください。
- 標準フィールドについては、AIP-148 をご覧ください。
- エラーについては、AIP-193 をご覧ください。
- デザイン パターンについては、デザイン パターンに関する AIP ガイダンスをご覧ください。
- インライン API のドキュメントについては、AIP-192 をご覧ください。
- proto3 の使用については、AIP-191 の構文セクションをご覧ください。
- バージョニングについては、AIP-185 をご覧ください。
- 下位互換性については、AIP-180 をご覧ください。
- ファイル構造については、AIP-191 のファイル レイアウト セクションをご覧ください。
- 用語の用語集については、AIP-9 をご覧ください。
次のトピックについては、このガイドの関連ページをご覧ください。