kstack-rest-api

HTTP API の route を設計するときの規約。理由を理解した上で適用すること。

1 つの route は 1 つのリソースだけを返し、画面用の集計は client で組み立てる

一覧画面が親ごとの件数・最新・先頭を出したいとき、複数テーブルを JOIN・集計して画面の形で返す route を作らない。リソース（テーブル）ごとに、親 id を複数受けてその行をまとめて返す一括取得 route を置き、件数や最新の組み立ては client が行う。

Bad: 画面専用の集計 route が items・payments・shipments を跨いで読む
GET /api/orders/summary
→ { orders: [{ id, itemCount, latestPayment, firstShipment }] }

Good: リソースごとの一括取得 route を並べ、client が組み立てる
GET /api/items?order_id=o1&order_id=o2      → { items: [...] }
GET /api/payments?order_id=o1&order_id=o2   → { payments: [...] }
GET /api/shipments?order_id=o1&order_id=o2  → { shipments: [...] }