Skip to content
DiaGO

REST Resource Design

Model your API as resources with uniform methods - naming, status codes, and the shapes that keep an API predictable.

REST's central move is to eliminate a whole category of design decisions. Instead of inventing a new procedure name for every operation (getOrder, fetchOrderById, retrieveOrderDetails), you model the API as a set of resources and manipulate every one of them through the same small set of HTTP methods. The variability lives in what your resources are, not in how you call them. That is what makes a well-designed REST API predictable: once a client knows your resource names, it can usually guess the rest.

Resources are the unit of design

A resource is a noun with identity, addressed by a URL:

  • Collections are plural nouns: /orders, /sensors, /bookings.
  • Items are collection members: /orders/42, /sensors/tmp-104.
  • Nested resources express true ownership, one level deep: /orders/42/lines works because an order line has no identity or lifecycle outside its order — the same reasoning behind composition in object modeling.

Reach for it

  • The child has no identity or lifecycle outside its parent
  • Clients always reach the child through the parent
  • Deleting the parent should remove the children with it

Avoid it

  • The child is shared by or referenced from several parents
  • Clients need to query the children across all parents at once
  • The path would end up nested more than one level deep

Deep nesting like /customers/7/orders/42/lines/3/product couples the client to your object graph. If a resource has its own identity, give it a top-level address and link to it by id.

The uniform interface

Each method has fixed semantics. Two properties matter most: safe (no state change, so responses can be cached) and idempotent (repeating the request yields the same outcome, so clients and proxies can retry on network failure without fear).

MethodSafeIdempotentSemantics
GETYesYesRead a resource or collection; never changes state
POSTNoNoCreate a member in a collection, or trigger processing
PUTNoYesReplace the resource entirely with the sent representation
PATCHNoNot guaranteedApply a partial modification to the resource
DELETENoYesRemove the resource; repeating the request changes nothing further

These are formal HTTP semantics, not style preferences. A GET that mutates state breaks caches and crawlers; a non-idempotent PUT breaks retry logic. PATCH is idempotent only if the patch itself is (setting status to shipped is; appending to a list is not).

Status codes that carry design meaning

Status codes are part of your contract. A small, consistently applied set beats an exhaustive one — pick these and use them the same way everywhere:

CodeMeaning in your design
200Success with a response body
201Resource created; return its URL in the Location header
204Success with nothing to return (typical for DELETE)
400Request is malformed — bad JSON, missing required field
401Authentication is missing or invalid — the server does not know who you are
403Authentication succeeded, but this identity is not permitted to do this
404No resource at this URL
409Conflict with current state — duplicate creation, stale version
422Well-formed request that fails semantic rules — a booking date in the past

The 401/403 distinction trips up many teams: 401 asks "who are you?" and invites the client to authenticate; 403 says "I know exactly who you are, and the answer is no." Conflating them makes debugging authorization bugs miserable.

Consistent shapes

Predictability extends into the payload:

  • Field casing: pick one convention (camelCase is the common JSON default) and never mix. Clients write mapping code once.
  • Error envelope: every error, from every endpoint, has the same shape — a machine-readable code for programs and a human message for logs:
{
  "error": {
    "code": "ORDER_ALREADY_SHIPPED",
    "message": "Order 42 shipped on 2026-07-08 and can no longer be cancelled."
  }
}
  • Pagination and filtering ride on query parameters: GET /orders?status=open&limit=50&cursor=eyJpZCI6NDJ9. Cursor-based pagination stays stable when rows are inserted mid-scan; offset-based is simpler but drifts.

Actions that do not fit CRUD

"Cancel an order" is not a create, read, update, or delete. The common convention is to model the action as a sub-resource or state transition rather than a verb in the path:

POST /orders/42/cancellation      -> preferred: the cancellation is a resource
POST /orders/42/cancel            -> RPC-style verb; avoid

This is convention, not formal REST law — but the reasoning is sound. A cancellation as a resource gets an address, a timestamp, a reason field, and can be fetched later (GET /orders/42/cancellation). A /cancel verb gives you none of that and reopens the naming free-for-all that resources were meant to close.

Versioning

The pragmatic default is a URL prefix (/v1/orders): visible, cache-friendly, trivial to route. But the cheapest version is the one you never ship — prefer additive changes (new optional fields, new endpoints) over breaking ones, and require clients to ignore fields they do not recognize. That is the Open-Closed Principle applied to a network contract: open to extension, closed to modification.

A contract, not your schema

Resources often mirror the entities in your ER model — orders, customers, payments — which is a useful starting point. But the API is a contract with outside clients, while the schema is an implementation detail you must remain free to change. Exposing internal columns blindly (surrogate keys, audit flags, denormalized caches) freezes your database design forever. Let a layer between them map storage rows to resource representations deliberately, deciding field by field what becomes public.

Practice

Design the resource layer for a small library system: members borrow copies of books, and a loan can be extended at most twice. Write down (1) the resource URLs for books, copies, members, and loans; (2) the method and status codes for creating a loan when the copy is available versus already borrowed; (3) how you model "extend a loan" without putting a verb in the path. Check yourself: is every path a noun, and would a 409 or a 422 fit the "already borrowed" case better — and why?