RESTful設計の本質を解く—URL階層で読み解くエンドポイント設計

はじめに

最近開発中に、既存のエンドポイントを見て、ふと違和感を覚えました。

GET /shops/:shop_id/orders/customers/:customer_id

動いているし、機能的には問題ありません。(実話ですがエンドポイントはダミーです)

気づいたきっかけは、私がエンドポイントを追加しようとした時に（ordersのstatusを更新する処理みたいな感じ）、既存のエンドポイントの拡張でいけるはずと思ったら、拡張しようと思ってたエンドポイントがない。なんでない？？あるはずなのにない。おかしい。どうなってる？？で、あぁ、これか、おかしいわってなった感じでした。

ボスに相談し、違和感とこうあるべきを伝えて「今そこ触ってる人います？」と確認しました。
コンフリクトがないことを確認して、その場で疎通してるフロント含めエンドポイントをリファクタすることになりました。

修正後はこうです。

GET /shops/:shop_id/customers/:customer_id/orders

たったこれだけです。でも、見た瞬間にスッと理解できるようになりました。

違和感の正体

私は感覚でエンドポイントこうが適切じゃない？？って考えたのですが、言語化するとRESTfulかどうかの問題だということがわかりました。
ただRESTfulを解説してもわかりにくいと思うのでこの事例を深ぼっていきます。

最初のエンドポイント、

/shops/:shop_id/orders/customers/:customer_id

これ、主語は何でしょう？

• orders？

• customers？

どっちの配下？URLの最後が「取得したいリソース」になっていないと、読んだときに引っかかります。

エンドポイントは仕様書でもあり、ドキュメントでもあるので直感的に読めるかは大事ですよね。

URLを住所として考える

URLを住所だと考えるとわかりやすそうです。

/shops/1/customers/5/orders

これは、ショップ1の中の顧客5の注文一覧という階層構造です。

住所って、上から順に絞られていきますよね。
「注文一覧の中の顧客」よりも、「顧客に紐づく注文」の方が、所有関係が明確です。

データの持ち主はどっちか？
この視点で見ると、後者の方が自然ではないでしょうか。

なぜ顧客配下に揃えたのか

今回欲しかったのは、特定顧客に紐づく注文一覧、つまり主語はordersであります。

RESTの基本形は、

/resource/:id/sub_resource

で考えると自然です。顧客が親リソースなら、その配下に注文がある。

これを逆にしてしまうと、「フィルタ」と「階層」が混ざります。
最初の形は、どこか操作ベースの匂いがしますよね。

設計を変えるメリット（DX・認可・拡張性）

フロントエンドが予測しやすい

顧客関連のデータはすべて

/shops/:shop_id/customers/:customer_id/◯◯

と揃えられます。

配送先や支払い方法などが増えても、構造を使い回せます。
予測できるURLは、開発体験を良くします。

認可ロジックが整理しやすい

顧客単位で権限をチェックするなら、

• そのショップに属しているか

• その顧客にアクセス可能か

と段階的に確認できます。

URLの階層と認可の階層が一致すると、コードも自然になります。

将来の拡張に耐えられる

設計の良し悪しは、その瞬間では分からないことも多いと思います。(経験がものをいう、、)
横展開したときに、初めて歪みが見えるってこともあると思います。
まさに今回拡張しようとした時に自然にできなくて、ここで修正しないとどんどん歪んでいくのでリファクタに至りました。

もし顧客に紐づく別のデータが増えたら、最初の構造では揃えにくかったはずです。

気づいたらすぐ直せるチームであること

今回よかったのは、違和感を口に出せたことだと思います。

「今そこ触ってる人いる？」「コンフリ大丈夫そ？」と確認し、エンドポイントの新設とともにリファクタすることができました。

設計って、時間が経てば経つほど直しづらくなると思います。

とっても気持ち悪いけど、、って思いながら開発するのは楽しさ半減します、、！
小さいうちに直せる文化は、本当にありがたいです。

まとめ

RESTfulであるかも重要かと思いますが、意識するのはそこではないと思っています。

• 主語は何か？

• 所有関係は自然か？

• 横に展開できるか？

こういう問いを持てるかどうかではないでしょうか。
そして、ふと感じたなんか違うを無視しないことが一番大事だと思います！

動くからOKにせずよりよく開発を進めていきたいものです🎵