Posted at

Google API Design Guideを読んで気になった点

More than 1 year has passed since last update.


モチベーション


  • 最近公開されたAPIデザインガイド

  • TechGiantのAPI設計から学びたい


Google API Design Guideとは


  • https://cloud.google.com/apis/design/

  • 2017 2/20 に公開された

  • 2014年からGoogle内部で実際に使われているAPIデザインガイド

  • REST, gRPC どちらにでも使えるように作られて

  • 決定版ではなく、日々追記されていく


基本はRESTful

https://cloud.google.com/apis/design/standard_methods

基本はRESTfulなので、知ってる人は見慣れた説明が並んでいる


カスタムメソッド

https://service.name/v1/some/resource/name:customVerb


  • httpメソッドにマッピングできない操作に対して、作って良い

  • :動詞 を最後につけて示す

  • メソッドは柔軟であるPOSTを推奨

  • PATCHで使うべきではない


カスタムメソッド使用例


  • VM再起動


    • 状態の遷移を行うAPIや、再起動リソースを作るAPIよりも、カスタムメソッドの方が直感的



  • メール送信


    • ドラフト→送信トレイへ移動、というデザインよりも、カスタムメソッドの方が直感的



RESTfulにこだわるよりも、ユーザが直感的にわかることが重要


エラー表現

https://cloud.google.com/apis/design/errors


  • エラーコードは少なければ少ないほど、クライアントのロジックが複雑にならなくて済む

  • status(エラーコード)は数列ではなく、人間でも読める英単語を使ってる


ページネーション


  • リスト化できるコレクションはどんな小さなものでもページネーションを実装しておくべき


    • 既存のAPIにページネーションを後から実装すると、元々全件返していたものが1ページ目(デフォルトページ)のみ返す、というような挙動の変更が発生してしまうから



Google API Design Guideに従ったAPIは

リクエスト: page_size と page_token パラメータ


レスポンス: next_page_token を返す

を使った共通の実装にしている



  • *ではなく-を使いましょう


    • URLエスケープの都合上



  • リソースの一部のフィールドだけ返せるようにすると便利

  • リソースをfullではなくbasicなものだけ受け取れるようにすると便利

  • APIドキュメントの作り方

などなど・・・


まとめ


  • RESTfulを推奨しているが直感的な設計を重視

  • 複数サービスで仕様が混濁しないように、ページネーションなどルールが厳格に決まっている

  • 仕様とドキュメントはprotoファイルで管理

  • API設計の資料として十分まとまっていて使えそう