REST API の設計原則

エンドポイントが 40 個あって、名前の付け方が全部違う

/getUserList、/user_delete、/fetchOrders。書いた人ごとに流儀が違うと、使う側は毎回ドキュメントを開くことになります。REST は、この命名を各自の趣味から取り上げて、HTTP がもともと持っている仕組みに寄せる考え方です。

URL は住所、動きはメソッド

REST では URL をリソースの住所として決めます。何をするかは URL に書かず、メソッドが担当します。

GET    /users        利用者の一覧
GET    /users/123    123 番の利用者
POST   /users        新しく作る
DELETE /users/123    123 番を消す

URL に動詞が出てこないのがポイントです。POST /createUser や POST /deleteUser は、メソッドが持っている意味を URL にもう一度書いているだけで、情報が二重になります。片方だけ直されて食い違う余地も生まれます。

ネストは /users/123/orders のように 2 階層までにしておくと扱いやすいです。それより深い参照は、URL を伸ばすよりクエリパラメータで表したほうが、後から絞り込み条件を足しやすくなります。

全部 200 で返すと、呼ぶ側がエラーに気づけない

失敗を本文の中だけに書いて、外側は成功として返す API があります。呼ぶ側は本文を解釈するまで失敗に気づけないので、共通のエラー処理が一切効きません。再送してよいかどうかも判断できません。

結果は数字で表します。成功したかどうかは、本文を読む前に分かる必要があります。

作成系では 2 つ覚えておくと役に立ちます。新しくリソースを作れたときの 201 と、処理はしたが返す本文が無いときの 204 です。削除の返事は 204 になることが多く、これが返っていれば、呼ぶ側は本文を読みにいきません。

失敗したときの本文も、形を決めて揃えておきます。機械が分岐に使う短い識別子と、人が読むための説明文を分けて入れておくと、呼ぶ側は識別子で処理を分け、説明文はそのまま画面に出せます。エンドポイントごとに本文の形が違うと、呼ぶ側にエラー処理が散らばります。

一覧を返す API は、いつか必ず重くなる

全件を返す一覧 API は、データが少ないうちは動きます。件数が増えた日にまとめて壊れます。最初から分割して返す設計にしておきます。

分割には 2 通りあります。?page=3&limit=20 のように何番目から欲しいかを指定する方式は、画面にページ番号を並べたいときに向きます。?cursor=xxxx&limit=20 のように前回の続きを指定する方式は、データが増減し続ける一覧でも取りこぼしや重複が起きにくくなります。

公開した API はいつか形を変えたくなるので、/v1/users のように URL の先頭に版を入れておきます。互換性を壊す変更が必要になったとき、古い版を残したまま新しい版を並べて出せます。