モチベーション
- 最近公開されたAPIデザインガイド
- TechGiantのAPI設計から学びたい
Google API Design Guideとは
- https://cloud.google.com/apis/design/
- 2017 2/20 に公開された
- 2014年からGoogle内部で実際に使われているAPIデザインガイド
- REST, gRPC どちらにでも使えるように作られて
- 決定版ではなく、日々追記されていく
基本はRESTful
基本はRESTfulなので、知ってる人は見慣れた説明が並んでいる
カスタムメソッド
https://service.name/v1/some/resource/name:customVerb
- httpメソッドにマッピングできない操作に対して、作って良い
- :動詞 を最後につけて示す
- メソッドは柔軟であるPOSTを推奨
- PATCHで使うべきではない
カスタムメソッド使用例
- VM再起動
- 状態の遷移を行うAPIや、再起動リソースを作るAPIよりも、カスタムメソッドの方が直感的
- メール送信
- ドラフト→送信トレイへ移動、というデザインよりも、カスタムメソッドの方が直感的
RESTfulにこだわるよりも、ユーザが直感的にわかることが重要
エラー表現
- エラーコードは少なければ少ないほど、クライアントのロジックが複雑にならなくて済む
- status（エラーコード）は数列ではなく、人間でも読める英単語を使ってる
ページネーション
- リスト化できるコレクションはどんな小さなものでもページネーションを実装しておくべき
- 既存のAPIにページネーションを後から実装すると、元々全件返していたものが１ページ目（デフォルトページ）のみ返す、というような挙動の変更が発生してしまうから
Google API Design Guideに従ったAPIは
リクエスト： page_size と page_token パラメータ
レスポンス： next_page_token を返す
を使った共通の実装にしている
他
- *ではなく-を使いましょう
- URLエスケープの都合上
- リソースの一部のフィールドだけ返せるようにすると便利
- リソースをfullではなくbasicなものだけ受け取れるようにすると便利
- APIドキュメントの作り方
などなど・・・
まとめ
- RESTfulを推奨しているが直感的な設計を重視
- 複数サービスで仕様が混濁しないように、ページネーションなどルールが厳格に決まっている
- 仕様とドキュメントはprotoファイルで管理
- API設計の資料として十分まとまっていて使えそう