CodePark/ questions / REST resource design
START PRACTICINGPRACTICE
Backend question · HTTP & API design › REST resource design

Design REST endpoints for orders that belong to customers, including listing a customer's orders and updating an order's shipping address.

GET    /orders?customerId=42&status=open
GET    /customers/42/orders
POST   /orders
GET    /orders/981
PATCH  /orders/981
DELETE /orders/981

Use plural nouns for collections, and add an ID for one member: /orders and /orders/981. The HTTP method says the action. So there is no /getOrders or /updateOrder.

The endpoints:

  • POST /orders creates an order. It returns 201 with a Location header that points to the new order.
  • GET /orders/981 reads one order.
  • PATCH /orders/981 with {"shippingAddress": {...}} updates part of the order.
  • DELETE /orders/981 removes or cancels the order. It returns 204 (success, no body).

For the customer relationship, a nested route like GET /customers/42/orders reads well, because orders belong to a customer. Keep nesting to one level. Also give every order its own top-level URL. This way you do not end up with long paths like /customers/42/orders/981/items/3.

A filter like GET /orders?customerId=42 is equally valid. It also combines easily with other filters. In all responses, use the same field naming style and the same status codes.

  • Use plural nouns for collections, IDs for single members, and HTTP methods as the verbs.
  • Use the correct status codes: 201 with a Location header for create, 204 for delete.
  • Use PATCH to update only part of a resource.
  • Keep nesting shallow, and give each resource its own top-level URL.
  • Use query parameters for filtering.