REST API Design Best Practices

Chapter 1 · Practice 2 of 4

Nest only for real ownership, and keep it to one level

From Resources and URLs

Why it matters

Nesting expresses that a resource belongs to another: /orders/7/items are the items of order 7. It stops helping after one level. /customers/3/orders/7/items/12/discounts forces clients to know every parent id just to reach a discount.

Guidelines:

  • Nest a collection under its parent when it cannot exist without it: /orders/7/items.
  • Give anything with its own identity a top-level URL too: /items/12.
  • Use query parameters for filtering, not paths: /orders?customer_id=3, not /customers/3/orders as the only way in.

If you find yourself writing three levels, the inner resource probably deserves its own top-level collection.