API設計メモ
iwamasaAPI設計について戦略を練るために色々調べるためのスクラップ
iwamasaMSさんのベストプラクティス良さそう
iwamasaAPIのホスト・ルートパスについて
大元のパスはどう設計するか？
大きく分けて2パターンで考えてみる
- サブドメインで分ける:
api.example.com - パスで分ける:
example.com/api
1の方が多いらしい
外部提供するなら1で良いけど、内部利用(internal)なら2でも良さそう。
また、サブドメインで分けるとインフラ側での対応も発生してくる。
インフラも含め、どこまでレイヤーを分けるかで決断するのが良い気がする。
ex.) APIだけ完全にインフラも分けてスケールも考慮した
→サブドメインで対応
ex.) モノリシックな既存サービス上に同居する形でAPIを生やしていく
→パスで対応するが、後からAPIだけ分けることも頭には入れておく
iwamasaバージョン管理について
そもそもバージョン管理は必要なのか？
→個人的には必須だと思う
理由: 破壊的変更が入る場合、利用者側の挙動が担保されないため
具体的な管理方法
- パスに埋め込む:
/v1/v2 - クエリに埋め込む:
/users?version=1
クエリで管理するとエンドポイントの解析をする時にクエリまで含めて解析する必要がある&前方一致で簡単に調べられないデメリットがありそう。
また、Railsなどのフレームワークを例として考えるとパスで管理した方がルーティング、Controllerから分けることが可能なのでパスの方が良さそう。
(クエリに埋め込んだ場合のメリットはまた今度調べてみる)
iwamasaRESTfulな設計を意識しよう
参考
ステートレス
ステートレスであること。リクエスト毎に必要な情報を全て渡すイメージ。
よくある例えだと、ハンバーガー屋さんで注文する時の会話だとイメージしやすい。
お客さん: ハンバーガーをください
店員さん: ハンバーガーですね。セットでドリンクはいかがですか？
→通常の会話だと、「ではコーラをください」とすれば良いが、ステートレスの場合は以下のイメージになる
お客さん: ハンバーガーとコーラをください
店員さん: ハンバーガーとコーラですね。セットでポテトはいかがですか？
お客さん: ハンバーガーとコーラとポテトをください
→このように、店員さん側では注文を記憶して引き継がないので毎回注文(リクエスト)に追加する必要がある
一意のリソース識別子
リソース(URL)は一意になるため、重複は許されない。
/users/1 はユーザーID1を意味し、必ず一意のリソースが返ってくる。
複数データでも同様で、 users であればユーザー一覧が返却される。
2回目にアクセスしたらユーザーじゃなくて会社一覧が返ってくるみたいなことはあり得ない。
(もちろん、パラメータによるページング、絞り込みはある)
HTTPメソッド
HTTPメソッドの規約に沿って命令を定義する。
GET 、POST 、PUT 、DELETE など。
GETならリソースの取得
POSTならリソースの登録 ※厳密には「送信」することなので用途は別でも使える
PUTならリソースの上書き(置き換え)
PATCHならリソースの更新 ※PUTとの違いは部分的な更新
DELETEならリソースの削除
※POSTとPUTとPATCHの違いについては結構言われるところなので興味があれば調べてみてください