Webエンジニアの技術ブログ

日々学んだことをアウトプットしていくためのブログです。

Web API設計の要点まとめ

全体的な

  1. APIは開発のUIのため利用者がわかりやすい設計にする

リクエスト(URL)

  1. HTTPメソッドで操作
  2. URLのエンドポイントは名詞で命名
  3. 単数系ではなく複数形で
  4. スネークケースではなく、ケバブケースで
  5. バージョンはURLに含める
  6. 条件(ソートなど)の指定は、リクエストパラメータで
  7. 関連データの場合親のリソースがわかるURLに(例: posts/:id/comments)

レスポンス

データの内部構造について

  1. 基本的にはXMLではなく、JSONを使用する
  2. APIのアクセスがなるべく少なくできるようなレスポンスデータ
  3. 必要のないプロパティは返さない(サイズを小さくするため)
  4. アクセス回数を少なくするためだからといって一度に大量のデータを返さない(その塩梅はAPIユースケースを考えてよしなに)
  5. 無駄にラップ(ネスト・入れ子)しすぎない(サイズ小さくするため)
  6. 大きい整数は文字列として返す(サイズ小さくするため)

命名について

  1. プロパティ名はキャメルケースで
  2. 扱うデータによって複数形or単数系の命名をする
  3. 完結でわかりやすい単語を用いる

エラー

  1. 適切なステータスコードを返す
  2. エラーの原因がわかるエラーメッセージ

セキュリティー

  1. SSL通信を行う(https)
  2. トークン認証を使う
  3. トークン認証はURLではなくヘッダに持たせる
  4. エラーメッセージに重要な情報(個人情報など)を載せない

参考資料

翻訳: WebAPI 設計のベストプラクティス - Qiita

API設計スキルを次のレベルに引き上げるベストプラクティス22選 - Qiita

Web API 設計入門