Web API The Good Partsのまとめ Part2

APIの設計

エンドポイントの設計とリクエスト形式

• 何をAPIとして公開するか決めよう

  • サービスのコアとなる機能を選ぶ
    →そのサービスの価値を生んでいるもの
    ex)ECサイト…商品の検索・購入

• URIのポイント

  • 短く入力しやすい
  • 人間(開発者)が読んで分かりやすい
  • 大文字小文字が混在していない
    • 基本は小文字
    • 大文字は404で返すケースが多い
  • 改造しやすい
  • サーバのアーキテクチャが反映されていない
    • 脆弱性をつかれるリスクがある
  • ルールが統一されている

• METHODについて

  • GET、POSTが多い（HTMLのフォームでもこの2つしか使えない）
  • POSTは本来新規情報の作成に使うべきで、情報の更新や削除には別のメソッドが適している。
  • X-HTTP-METHOD-Overrideヘッダ
    • 仕様でGETとPOSTメソッドしか使えない場合、本当に使いたいメソッドを記述するヘッダ
  • _methodパラメータ
    • X-HTTP-METHOD-Overrideヘッダ同様に本当に使いたいメソッドを記述するパラメータ
    • Ruby on Railsで使用されている

WebAPI設計の基本

🔑 「あるデータの集合」と「個々のデータ」をエンドポイントとして表現し、それに対してHTTPのメソッドで操作を表していく

エンドポイント設計で注意すべきこと

1. 複数形の名詞を利用する
2. 利用する単語に気を付ける
3. スペースやエンコードを必要とする文字を使わない
4. 単語をつなげる必要がある場合はハイフンを利用する
   • _(アンダースコア)だとリンクアドレスに下線が引かれた場合見づらい
     • profile_image

検索とクエリパラメータの設計

• データ一覧を取得するエンドポイントに絞り込みをかけて検索させる
  • 絞り込みするのに必要なのがクエリパラメータ
• クエリパラメータの取得数と取得位置
  • page/per_pageやlimit/offsetなどが一般的
  • limit/offsetの方が自由度が高い
    • これらは取得位置を相対的に指定するものだが、これには
      1. データ量が増えれば増えるほど時間がかかる
      2. 更新頻度の高いデータの場合、データの不整合が起こりうる
         という問題点がある。