RESTとルート設計

「機能が増えると REST では足りなくなる」という話をよく聞きます。

このガイドの設計方針に従うと、ルートは比較的シンプルに保てるのではないか、という考えを書いておきます。

ルートが増える傾向

ルートが増えるのは、画面が増えることと関係していることが多いです。

# 画面ごとにルートを作ると...

GET    /users/new           新規登録画面
POST   /users/new/confirm   確認画面へ
GET    /users/new/confirm   確認画面
POST   /users/new/back      入力に戻る
POST   /users/new/submit    登録実行
GET    /users/new/complete  完了画面

1つの「ユーザー作成」に 6ルート。こういうケースは珍しくありません。

この設計方針との関係

このガイドの方針	減る可能性のあるルート
確認画面を減らす	`/confirm`, `/back`, `/complete`
登録画面を統合する	`/new` 系
編集画面を統合する	`/edit` 系

画面が減れば、ルートも減る傾向にあります。

REST の基本形

参考として、REST の基本形は以下の5つ。

GET    /users          一覧
GET    /users/:id      詳細
POST   /users          作成
PUT    /users/:id      更新
DELETE /users/:id      削除

このガイドの設計方針に従うと、この基本形に近づきやすいのではないかと考えています。

状態遷移の操作

業務システムでは、CRUD だけでは足りないことが多いです。

POST   /orders/:id/submit    申請
POST   /orders/:id/approve   承認
POST   /orders/:id/reject    却下
POST   /orders/:id/cancel    取消

これらは業務上必要な操作であり、REST の基本形とは別に存在して構いません。

リソース中心とアクション中心

両方のアプローチがあり、混在しても問題ありません。

# リソース中心（CRUD）
GET    /orders/:id
PUT    /orders/:id
DELETE /orders/:id

# アクション中心（業務操作）
POST   /orders/:id/submit
POST   /orders/:id/approve

重要なのは、URL を見れば何をするか分かる こと。

命名の一貫性

# 推奨: リソース + 動詞
POST /orders/:id/submit
POST /orders/:id/approve
POST /orders/:id/ship

# 避けたい: リソースが見えない
POST /submitOrder/:id
POST /doApproval

# 避けたい: 何をするか分からない
PUT  /orders/:id/status
PATCH /orders/:id

ルート数の内訳を見る

ルートの数だけでなく、何のルートか を見ることが大切。

健全な例（8ルート）

# CRUD: 5ルート（基本形）
GET    /orders
GET    /orders/:id
POST   /orders
PUT    /orders/:id
DELETE /orders/:id

# 状態遷移: 3ルート（業務上必要）
POST   /orders/:id/submit
POST   /orders/:id/approve
POST   /orders/:id/cancel

業務に必要な操作がルートになっています。

見直したい例（11ルート）

# CRUD: 5ルート
GET    /orders
GET    /orders/:id
POST   /orders
PUT    /orders/:id
DELETE /orders/:id

# 確認画面系: 4ルート
POST   /orders/confirm
GET    /orders/confirm
POST   /orders/back
GET    /orders/complete

# 状態遷移: 2ルート
POST   /orders/:id/submit
POST   /orders/:id/approve

UI の工程（確認、戻る、完了）がルートになっています。

逆に考えると

「REST で収まらない」という状況が頻発するなら、それは設計を見直すきっかけかもしれません。

こういうルートが多いなら	確認すること
`/confirm`, `/back`, `/complete`	UI の工程がルートになっていないか
`/new` と `/edit` が別々	画面を分けすぎていないか
1リソースに15ルート以上	リソースを分割すべきかもしれない

ただし、ルート数が多いこと自体は問題ではありません。業務上必要な操作であれば、10ルートでも意図が明確なら保守しやすいです。

REST に縛られすぎない

REST は便利な共通言語ですが、目的ではありません。

注意したいこと

無理に CRUD に押し込めると、リクエストボディが肥大化します
PUT /orders/:id で全部やろうとすると、何が変わるか分からなくなります
「RESTful かどうか」より「使いやすいかどうか」が大切です

業務の言葉を使う

業務システムには業務の言葉があります。

# 業務の言葉をそのまま使う
POST /orders/:id/submit    # 申請
POST /orders/:id/approve   # 承認
POST /orders/:id/reject    # 却下

# 無理に CRUD に押し込めない
PUT /orders/:id { status: 'approved' }  # 何をしているか分かりにくい

申請、承認、却下。これらを無理に CRUD に押し込める必要はありません。

チェックリスト

良い兆候

リソース名が名詞（/users, /orders）
1リソースあたり 5〜10 ルート
URL を見れば何をするか分かる
業務の言葉がルート名に使われている

警告サイン

/confirm, /back, /complete が多い → UI の工程がルートになっている
/doSomething のような動詞だけの URL → リソースに紐づいていない
1リソースに 15 ルート以上 → リソースの分割を検討

補足

このガイドが言いたいのは「REST の基本形に収めろ」ということではありません。

UI の工程（確認画面、完了画面）がルートになっているなら、UI を見直す余地がある
業務上必要な操作（申請、承認）がルートになっているなら、それは健全

ルート設計の複雑さを感じたら、何が原因で複雑になっているか を見分けることが大切です。