概要
このドキュメントは、Google Cloudが公開しているAPI Design Guide（通称AIP: API Improvement Proposals）をもとに、API設計の「考え方」を15分程度で把握できるようにまとめたものです。個別のHTTPメソッドの書き方より、なぜそのリソース構造・命名・エラー設計になるのかという判断基準を中心に扱います。
このガイドは2014年からGoogle社内で使われ、Cloud APIをはじめ多数のGoogle APIの設計に使われてきたものです。REST APIだけでなくgRPC APIにも適用される、より一段抽象度の高い「API設計の型」だと捉えてください。
1. 全体思想：リソース指向設計
このセクションで分かること
API設計の基本単位が「機能」ではなく「リソース（名詞）」である理由と、その考え方がどう設計判断に効いてくるかが分かります。
Google Cloud API Design Guideの中核にあるのは「リソース指向設計（resource-oriented design）」という考え方です。これはRESTに近い思想ですが、Google独自のパターンも含みます。設計時に考えるべき順序は次の通りです。
- APIが提供するリソース（名詞）
- リソース同士の関係・階層構造
- 各リソースのスキーマ（フィールド構成）
- 各リソースが持つメソッド（動詞）
つまり、先に「何のエンドポイントが必要か」を考えるのではなく、先に名詞（データモデル）を固め、その後に少数の標準的な動詞を割り当てるという順序が推奨されています。
- Good：
users,books,ordersのようなリソースを軸に設計し、操作は標準メソッド（後述）に寄せる - Bad：
/getUserOrders,/cancelOrderByIdのような機能単位のエンドポイントを都度作る
また、APIをデータベーススキーマと1対1に一致させることはアンチパターンとされています。DBの都合をAPIの表面にそのまま持ち込むと、内部実装とAPIが強く結合してしまうためです。
もう一つ重要なのが「ステートレス」という原則です。クライアントとサーバーの各やり取りは独立しており、サーバー側は状態を持ちません。リクエストは単体で完結し、以前のリクエストへの依存を前提にしないという設計姿勢がAPI全体を貫いています。
2. リソースとメソッドの設計
このセクションで分かること
「コレクション」という考え方と、5つの標準メソッドで大半の操作をカバーするという設計方針が分かります。
コレクションと標準メソッド
リソースは基本的に「コレクション（同じ種類のリソースの集まり）」として階層化されます。例えば「出版社が本を複数持つ」なら、publishers というコレクションの下に books というコレクションがぶら下がる形です。
そして各リソースには、原則として次の5つの標準メソッドのいずれかを割り当てます。独自の動詞をむやみに増やさず、この語彙に寄せるのがGoogle流です。
| メソッド | リクエストにリソースを含むか | レスポンスの中身 |
|---|---|---|
| Get | 含まない | リソースそのもの |
| List | 含まない | リソースの配列 |
| Create | 含む | 作成後のリソース |
| Update | 含む | 更新後のリソース |
| Delete | 含まない | 空 |
すべてのリソースは最低限 Get をサポートしなければならないとされています。作成・更新・削除のあとにクライアントが状態を確認できる手段が必須だからです。また、単一にしかなり得ない特殊なリソース（シングルトン）を除き、List も基本的に必須です。
標準メソッドで足りない場合：カスタムメソッド
既存の5メソッドにうまく当てはまらない操作（例：メール送信、バッチ処理、インポート/エクスポートなど）には「カスタムメソッド」を使います。これは新しいHTTP動詞を作るのではなく、通常POSTを使い、URIの中に動詞を埋め込む形（例：books/1234:archive）で表現します。標準メソッドを優先し、カスタムメソッドは「本当に当てはまらないとき」の逃げ道という位置づけです。
強整合性という前提
作成・更新・削除の操作が完了した後、そのリソースへのGetリクエストは必ず最新の状態を返さなければならない、という強い一貫性の保証が求められています。クライアントが「操作Aが終わったから次にBを行ってよい」と判断できるようにするためです。
3. リソース名の設計
このセクションで分かること
URLパスがどういう文法規則で組み立てられているか、そして name という予約フィールドの意味が分かります。
パス構造の基本文法
リソース名は、コレクション識別子とリソースIDが交互に並ぶパスとして表現されます。
publishers/123/books/les-miserables
users/vhugo1802
- コレクション識別子（
publishers,booksなど）は複数形にする - コレクション識別子は
camelCase、先頭は小文字 - リソースID部分は基本的に小文字を使う（大文字は避ける）
- 記号は原則DNS名で使える文字の範囲に収める（URLエスケープが必要な文字は避ける）
nameフィールドの特別な扱い
すべてのリソースは、自分自身の名前を格納する name という文字列フィールドを持たなければならないとされています。この name は予約された意味を持つため、他の用途（例えば表示名）には使わず、display_name のように形容詞を付けて区別します。
同様に、あるリソースの「親」を指す場合は parent という名前のフィールドを使うのが慣習です。これも name と同じく、目的外の用途で使うべきではありません。
なぜタプルではなく「名前」なのか
リソースを (bucket, object) のようなタプルで特定する設計もあり得ますが、ガイドはこれを避けるべきとしています。タプルは開発者が覚えにくく、ロギングや権限管理のような横断的な仕組みと相性が悪いためです。文字列1本の「名前」に統一することで、Long-running Operationsのような汎用的な仕組みが多くのAPIをまたいで再利用しやすくなる、という設計上の利点があります。
4. エラー設計の考え方
このセクションで分かること
エラーが単なる「メッセージ文字列」ではなく、機械可読な情報を含む構造化されたものとして設計されている点が分かります。
3つの要素で構成されるエラー
ガイドでは、エラーは次の3つの情報を持つ構造として定義されています。
code：NOT_FOUNDやPERMISSION_DENIEDのような標準エラーコードmessage：人間（開発者）向けの説明文。技術的な前提知識を要求しない、簡潔で解決につながる文言が推奨されるdetails.ErrorInfo：reason（NO_STOCKのようなUPPER_SNAKE_CASEの短い識別子）とdomain（サービス名）を持つ、機械可読な識別情報
この3層構造の狙いは、クライアント側がメッセージ文字列をパースしなくてもエラーの種類を判定できるようにすることです。人間向けの説明と機械向けの識別子を分離する、という設計思想がここに表れています。
権限エラーの順序
アクセス権限がないユーザーに対しては、リソースの存在有無に関わらず先に PERMISSION_DENIED を返すべきとされています。「存在するかどうか」を先に教えてしまうと、それ自体が情報漏えいになり得るためです。権限チェック→存在チェックという順序は覚えておくと良いポイントです。
部分エラーは避ける
一括処理などで一部だけ失敗するケース（部分エラー）は、原則として避けるべきとされています。エラーコードの意味があいまいになり、クライアント側に専用のエラーハンドリングを強いることになるためです。どうしても必要な場合は、長時間実行オペレーション（非同期処理）の仕組みに乗せることが推奨されています。
5. AIコーディングを見据えた観点
このセクションで分かること
AIにAPI設計・実装を任せる際に、事前に共有しておくと精度が上がる語彙と、AIが見落としやすいポイントが分かります。
事前に伝えておくと良いこと
- 「標準メソッド（Get/List/Create/Update/Delete）に寄せて設計して、当てはまらない操作だけカスタムメソッドにして」という方針
- リソース名のパス規則（複数形コレクション名、
name/parentフィールドの予約用途） - エラーレスポンスの構造（
code/message/ErrorInfo.reasonの3点セットで返すこと）
AIが誤りやすいポイント
- 機能ベースのエンドポイント（
/getUserOrdersのような動詞先行の設計）を提案しがちです。リソース指向であれば「本当に標準メソッドで表現できないか」を問い直す価値があります。 - エラーメッセージだけを返して
reasonのような機械可読な識別子を省略しがちです。クライアント側でのエラーハンドリングのしやすさに直結するため、レビュー時に確認すると良い点です。 nameのような予約語を、意味の異なる用途（表示名など）に流用してしまうことがあります。予約フィールドの意味を事前に共有しておくと防ぎやすくなります。
参考文献一覧
- Cloud API Design Guide（トップページ） — Google Cloud公式
- AIP-121: Resource-oriented design — Google AIP公式
- AIP-122: Resource names — Google AIP公式
- AIP-130: Methods — Google AIP公式
- AIP-193: Errors — Google AIP公式
- AIP一覧（トップページ） — Google AIP公式