APIの設計に、Googleのガイドが参考になる

アプリやJavaScriptなどのフロントエンドとバックエンドを連携する際に使うAPIについてGoogleがガイドを作っているので、読んでみました。

この記事でいう「API」は、主に「REST API」を指していますが、以下のGoogleのガイドは gRPC API（Google独自のプロトコル） にも対応しています。

API 設計ガイド
https://cloud.google.com/apis/design?hl=ja

詳しくは上記のサイトを参照いただくとして、ここでは気になった点だけ抜き出してみます。

リソース名とメソッド

リソース名とは、簡単に言うと「URL」にあたるものです。
例えば以下のような命令だとします。

サービス名（ベースURL）：api.example.com
コレクションID（種別）：books
リソースID（個別データID）：1234

上記の場合、「リソース名」は以下となります。

//api.example.com/books/1234

種別にあたる「リソースID」は基本的にはlowerCamelかつ複数形で表現し、複数形がない単語（ evidence や weather 等）は単数形でOKです。

メソッドに関して、一般的にAPIのメソッドはCRUD（Create、Read、Update、Delete）と表現されますが、Googleのガイドでは以下の6種です。

• List・・・GET メソッド
• Get・・・GET メソッド
• Create・・・POST メソッド
• Update・・・PUT または PATCH メソッド
• Delete・・・DELETE メソッド

命名規則

• 基本は「正しいアメリカ英語」です。licence（英語）→ license（米語） や、 colour （英語） → color （米語） など。
• 一般的な短縮語（「API」など）は使用可能。
• なるべく同じ名前は使わない。
• 「instance」「info」「service」など一般的すぎる名前を使わず、もっと具体的にする。（「bookInfo」「bookUploadService」など）
• プログラミング言語の仕様と競合するような名前は慎重に検討する。（PHPだと「constructor」などのマジックメソッドがこれにあたるかも？）
• 更新データなどのフィールド名
  • スネークケース 。（逆に、フィールド名以外の全てのものはキャメルケース。）
  • 前置詞（for、during、at など）を含めないことが推奨。（ reason_for_error → error_reason など）
  • 後置形容詞（名詞の後に配置される修飾語）を使用しないことが推奨。（ items_collected → collected_items 、objects_imported → imported_objects など）
  • 配列などの繰り返しデータは適切な複数形にする。（series → series、data → datum、index → indices など）

カスタムメソッド

例えば「Delete」ではなく「Remove」や「Clear」など独自のメソッドを使いたい場合はコロン「：」で区切って指示します。

//api.example.com/books:clearAll

エラーハンドリング

エラーは「error」キーの値に情報をまとめるようです。

{
  "error": {
    "code": 401,
    "message": "認証情報が不正です",
    "status": "UNAUTHENTICATED",
    "details": [{
      "@type": "type.googleapis.com/google.rpc.RetryInfo",
      ...
    }]
  }
}

Googleではエラー時の返却データを細かく設定しているようです。

https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto

---

以上です。
さらに詳しい資料が満載な公式ドキュメントをぜひ一読することをお勧めします。

https://cloud.google.com/apis/design?hl=ja