eng-docs

API 設計クイックリファレンス

4 min read

API 設計クイックリファレンス

対象

  • そのサービスのコアの価値のある部分をすべてAPI経由で行えるようにする

URI

  • セキュリティの観点から、サーバー側が何で実装されているか分からないようにする

ホスト名

  • ホスト名(api.example.com)
  • ホスト名(ドメイン名)はハイフンは許可されているもののアンダースコアは使えず、大文字小文字の区別がない
  • オープンなAPIとある程度クローズドなAPIを異なるエンドポイントで公開

バージョン

  • ドメイン名の次はバージョン(v2等)
  • 後方互換性を失ってもよいと判断できるほどの本当に大きな変更を行いたいときにのみ、バージョンを上げる

パス

  • 一意なリソースを表すのに必要な情報はパス

  • リソースは小文字で複数形にする

  • なるべく少ない単語数で表現する

  • 複数のAPIを見比べて、最もよく使われている、最もしっくりくる単語を選ぶ

  • 標準化された単語以外は極力省略をしない

  • 単語をつなげる必要がある場合はハイフンを利用する

  • 検索のためのエンドポイントはsearchという単語を入れる

クエリパラメーター

  • 省略可能なパラメーターはクエリパラメーターにする
  • どこから何件取得するかはoffset/limitパラメーターを使う
  • 全文検索のわかりやすい例として、Googleの検索もクエリパラメータ名はq
  • 取得する項目を利用者が選択可能にする(fieldsパラメーター)

HTTPメソッド

メソッド名説明
GETリソースの取得
POSTリソースの新規登録
PUT既存リソースの更新
DELETEリソースの削除
PATCHリソースの一部更新
HEADリソースのメタ情報取得

設計

  • ユースケースに沿った形で、できるかぎり少ないアクセス回数ですむAPI設計を心がける

データ構造

  • データ構造はなるべくフラットにしたほうがよいが、階層構造を持ったほうがわかりやすい場合もある
  • 通常時もエラー時もレスポンスデータをオブジェクトに統一する

レスポンスヘッダー

ステータスコード

ステータスコード意味
100番台情報
200番台成功
200OK
201Created
202Accepted
204No Content
300番台リダイレクト
301Moved Permanently(メソッドの変更を許可)
302Found(メソッドの変更を許可)
304Not Modified
307Temporary Redirect
400番台クライアントエラー
400Bad Request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
408Request Timeout
409Conflict
429Too Many Requests
500番台サーバーエラー
500Internal Server Error
502Bad Gateway
503Service Unavailable
  • ぴったりくるステータスコードが存在しなかった場合には“200”や“400”、“500”といった “00”で終わるステータスコードを付けるようにする

Content-Type

  • Content-Type: application/json; charset=utf-8
  • X-Content-Type-Options: nosniff

レスポンスボディ

各データ

  • レスポンスのキーはなるべく少ない単語数で表現する
  • レスポンスのキーが続く複数の単語を連結する場合、その連結方法はAPI全体を通して統一する(JSONではキャメルケースを使うのがよい)
  • レスポンスのキーにスネークケースを利用しているAPIはたくさんある
  • 日時の形式はRFC3339にする(1995-12-17T03:24:00Z or 1995-12-17T03:24:00+09:00)

エラー時

  • エラーメッセージはレスポンスボディに配列で格納する
  • エラーはセキュリティやその他の理由から問題が発生するようなケースでは、あ えてやや情報を曖昧にする

バックリンク