ボクココ

個人開発に関するテックブログ

REST な API とは何か

以前、こんな 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なりでコンタクト取って頂ければ、一緒に考えることはできるので連絡頂きたい。