以前、こんな REST API を作って欲しいと言われて、その仕様をみたらこの方は本当にRESTの意味をわかっているのかと疑問になる設計だった。意外とRESTって言葉は流行っていても、それが一体なんなのかしっくり来ない方もいるようなので、ここでRESTについて自分なりの理解ではあるがまとめてみようと思う。
REST, それは資源、モノベースのURL
完全に間違えているREST とは例えば以下のようなURL設計だ。
GET /api/listItem GET /api/showItem?id=xxxxx POST /api/createItem POST /api/updateItem?id=xxxxx POST /api/deleteItem?id=xxxxx
この場合は、動詞があるのでぱっと見た感じ意味が分かりやすい。アイテム一覧、アイテム詳細、アイテム作成、アイテム更新、アイテム削除。 ただこれはRESTではなく、ただのAPIだ。正しくはこうだ。
GET /api/items GET /api/items/xxxxx POST /api/items PUT /api/items/xxxxx DELETE /api/items/xxxxx
このように、 items というアイテム(資源)の集合をHTTPメソッドを用いてURLに設計にするのがRESTというものだ。APIのURLに動詞が入っている場合は注意だ。間違っている可能性が高い。
さて、RESTを意識してもだんだんと難しい場合が出てくる。次の例に行こう。
ネストされたリソース
ユーザーに対してその人の持つその他の資源についてどうURLで表現すれば良いのだろうか。 例えば以下のようなURLを見てみよう。ありがちなパターン。
GET /api/coupon?user_id=xxxxx POST /api/coupon?user_id=xxxxx PUT /api/coupon?user_id=xxxxx&coupon=yyyyy
上から順に、自分のクーポンコードの取得、クーポンコードの生成、クーポンコードの適用といった想定だ。まぁこれでも悪くはないんだけど、RESTっぽくするにはもっとusersとの関連を示すべきだ。自分の理想は以下の通り
GET /api/users/xxxxx/coupon POST /api/users/xxxxx/coupon PUT /api/users/xxxxx/coupon?coupon=yyyyy
こんな感じでURLを設計すれば、ほっとんどのことはRESTの設計で作ることができる。今までURLの作り方はかなり自由で悩んでいた人も多いだろうが、このRESTの制約を守るとかなり規則的にURLを設計することができる。新しいURLを作成する際に、何の資源に対してのリクエストなのか、というのを常に考えるようにしよう。
RESTのメリット
ではRESTにすると何が嬉しいのか。
その一つはさっき述べたように、URL設計に規律が生まれるという点だ。URLを見た時点で、ソースコードのどの部分なのかがはっきりわかる。ルーティングでごにょごにょしているコードを読む必要が無くなる。
そしてもう一つがそのAPIクライアントのメリットだ。規律を守ったURLにすることで、RESTのAPIクライアントを作成もしくはGithubなどから拝借するだけで簡単にAPI通信処理のコードを書くことができる。これも規約があるからこそコードの共通化をすることができるのだ。
まだ慣れないうちは、どうやってこれをURL設計すれば良いのかわからないかもしれない。そんな時は是非Twitterなりでコンタクト取って頂ければ、一緒に考えることはできるので連絡頂きたい。
