Web API The Good Parts 読書メモ

2.3 HTTPメソッドとエンドポイント

• URIとHTTPメソッドの関係性
  • URI: "操作する対象"＝リソース
  • HTTPメソッド ："何をするか"

エンドポイント設計時の注意点

• 複数形の名詞にする（users, updates）
• 利用する単語に気をつける
  • 例：searchとfindの区別
    • search: 探す場所を目的語にとる
    • find: 探すものを目的語にとる
    • わからなければ、類似のAPIの単語を調べてみる
• スペースやエンコーディングが必要な文字を使わない（SJISなど）
• 単語をつなげるときはハイフンつなぎ（例：profile-image）
  • 好みの問題。特にポリシーがなければハイフンつなぎが無難

クエリパラメータの設計

• 大量のリソース（1万以上のデータ取得とか）の検索の際は、クエリパラメータで一回の上限を区切って複数回に分けてデータ取得（ページネーション）
• 取得のときによく使われるキーワード
  • 取得数：limit, count, per_page
  • 取得位置：page, offset, cusor
  • よくある組み合わせ：per_pageとpage, limitとoffset

クエリパラメータとパスの使い分け

• クライアントが特定パラメータ指定したいとき、パラメータをいれるのはクエリパラメータかパスか
  • 判断基準
    • 一意にリソースを表す必要があるか
      • パスの方が良い（URI自体がリソースを表すから）
    • オプショナル（省略可能）か
      • クエリパラメータの方が良い