REST API Design Best Practices: Resource Modelling, Idempotency, and Versioning

An API Is a Product, Not a Mirror of Your Database

A familiar failure mode: expose every database table as a CRUD endpoint and you end up with a pile of /getUsers, /createOrder, and /updateUserStatus. It works, but every new client needs bespoke glue, and every schema change has to be announced to every consumer.

The value of REST is not that it looks tidy. It is that an endpoint can be guessed correctly without reading the documentation. Getting there starts with resource modelling, not with URL strings.

When you are debugging response bodies and matching up fields, pasting the returned JSON into a JSON formatter is the fastest first step; for deeply nested payloads, a JSON viewer that lets you collapse and expand beats scrolling through a terminal.

1. Resource Modelling: First Principles of URL Design

Use nouns, not verbs

The URL names the resource; the HTTP method names the action. Putting a verb in the URL throws away the semantic layer HTTP already gives you for free.

Express hierarchy, but stop at two levels

/users/1/orders/2/items/3 is technically valid, but it locks clients into one fixed traversal path and forces a parent-existence check at every level.

Rules of thumb:

• Use hierarchy when the relationship is exclusive and strongly owned: /users/1/orders
• Flatten past two levels and filter with query parameters: /orders?userId=1&status=paid
• If a resource has a globally unique id, let it be reachable as a top-level resource: /orders/2

Naming consistency

What about non-CRUD actions

Some operations never map cleanly onto CRUD — publish, cancel, batch recalculate. Three options, in priority order:

1. Model the action as a resource: POST /orders/1/cancellations. Cancelling becomes creating a cancellation record, which is clean and auditable.
2. Model it as a state field: PATCH /orders/1 with { "status": "cancelled" }.
3. Only as a last resort, a verb suffix: POST /orders/1:publish. Acceptable, but document clearly that it is not a resource.

2. HTTP Methods: Semantics and Idempotency

For the full semantics and side-effect matrix, see the HTTP methods reference.

Idempotency is not an academic concern

Idempotent means executing the same request N times leaves the server in the same state as executing it once.

It matters because retries are guaranteed to happen: mobile network handovers, gateway timeout replays, at-least-once queue delivery, a user double-tapping a button. Any non-idempotent write endpoint produces duplicates without protection.

The two most common traps:

• Creating orders with POST: two taps, two orders. Fix it by having the client send an Idempotency-Key header (a UUID generator is all you need), storing it server-side as a unique key for 24 hours, and replaying the original result on a hit.
• Relative deltas via PATCH: { "balanceDelta": -100 } retried twice charges two hundred. Submit the absolute value { "balance": 900 } instead and idempotency follows automatically.

What POST should return

On success return 201 Created with the new resource URL in Location:

HTTP/1.1 201 Created
Location: /orders/9f3c...

If creation is asynchronous, return 202 Accepted with a status endpoint. Do not return 200 and pretend the work is done.

3. Status Codes: Layer Them, Do Not Return 200 for Everything

Returning 200 for everything and putting the error code in the body is the most common anti-pattern. It blinds monitoring (every request looks successful), confuses gateway caches, and forces clients to parse the body just to learn whether the call worked.

For the complete list and common misuses, see the HTTP status codes reference.

Boundaries that are easy to get wrong:

• 400 vs 422: when the syntax is valid but the semantics fail (end date before start date), use 422 Unprocessable Entity; malformed syntax is 400.
• 401 vs 403: 401 means we do not know who you are; 403 means we know who you are and the answer is no. An authenticated user without permission gets 403.
• 404 vs 403: returning 404 to hide the existence of a resource is a legitimate security practice.
• 409 Conflict: a state conflict — duplicate submission, version mismatch, insufficient stock. It tells the client that retrying is useless until the state changes.
• 429 Too Many Requests: rate limited. You must include Retry-After, otherwise clients retry blindly and turn overload into an avalanche.

4. A Uniform Error Format

Use RFC 7807 application/problem+json as the shared envelope:

{
  "type": "https://api.example.com/errors/order-already-paid",
  "title": "Order already paid",
  "status": 409,
  "detail": "Order 9f3c has already been paid and cannot be modified.",
  "instance": "/orders/9f3c",
  "code": "ORDER_ALREADY_PAID",
  "errors": [
    { "field": "quantity", "reason": "must be greater than 0" }
  ]
}

Key points:

1. type is the stable contract. Clients branch on it, never on detail prose.
2. code is a deliberate extension for localisation and monitoring — the same code can be grouped by directly in log queries.
3. errors carries field-level validation detail. Form endpoints are unusable without it.
4. Never echo stack traces, SQL, internal hostnames, or raw user input.

When a team needs to freeze the contract, generating a schema from real responses with a JSON Schema generator drifts far less than hand-written docs; TypeScript clients can generate types directly with JSON to TypeScript.

5. Pagination, Filtering, and Sorting

Filtering and sorting should follow one global convention instead of being reinvented per endpoint:

• Filtering: ?status=paid&created_after=2026-01-01
• Sorting: ?sort=-created_at,amount (a leading minus means descending)
• Field selection: ?fields=id,status,total (saves bandwidth, but be explicit about its effect on cache keys)
• Totals: do not return total on every call; it is often the most expensive COUNT(*) in the system. Offer ?count=true when it is actually needed.

When comparing two revisions of a response, JSON Diff is far more reliable than eyeballing fields one by one.

6. Versioning

More important: avoid bumping the version at all. These changes are backward compatible and need no new version:

• New optional request fields
• New response fields (clients must ignore unknown fields)
• New endpoints
• New Link headers or new error type values

These are breaking and require a new version or a staged rollout:

• Removing or renaming a field
• Tightening validation rules
• Changing a field type or unit
• Changing error semantics

7. Caching and Conditional Requests

Caching offers the highest performance return for the smallest change, and is the step most often skipped.

Working through a checklist is the cheapest way to catch gaps: HTTP headers reference.

Practical notes: GET is cacheable by default, which is exactly why it must never carry side effects (that is the real problem with delete-by-GET designs). Mark writes explicitly with no-store. Authenticated personalised responses must carry Cache-Control: private, otherwise a shared cache can leak one user's data to another.

8. The Minimum Consensus on Auth

• Force HTTPS and 301-redirect plain HTTP. Certificate and TLS details are covered in the HTTPS certificate guide.
• Do not invent an auth protocol. Use OAuth 2.1 / OIDC or a mature session mechanism. Token design, signing, and common pitfalls are in JWT security best practices.
• Never store passwords in plaintext; use bcrypt, Argon2, or scrypt. The full tradeoff is in the password hashing guide, with the matching bcrypt hash tool.
• Enforce authorisation server-side. Hiding a button in the UI is not access control.
• Rate-limit by identity, not by IP, or users behind the same NAT will block each other.

When debugging a call, feeding a request copied out of the browser into cURL to code produces client snippets for each language far more reliably than transcribing headers by hand.

9. Anti-Pattern Checklist

Ship Checklist

Before releasing, verify each item:

1. All URLs use plural nouns, lowercase, hyphenated, no verbs
2. HTTP methods line up with semantics, safety, and idempotency
3. Every write endpoint can answer "what happens on a retry"
4. Non-idempotent writes support Idempotency-Key
5. Status codes are layered 2xx/4xx/5xx; nothing returns 200 for everything
6. Both 429 and 503 carry Retry-After
7. Errors are uniformly application/problem+json with a stable type and a business code
8. Validation errors include field-level detail
9. Error bodies contain no stack traces, SQL, or internal hostnames
10. Cursors are used once paging goes past two levels deep
11. Filtering, sorting, and field-selection syntax is globally consistent
12. Backward-compatible changes did not bump the version; breaking ones did and are staged
13. GET is safely cacheable, writes declare no-store, personalised responses declare private
14. HTTPS everywhere, HTTP is 301-redirected
15. Authorisation enforced server-side; rate limiting keyed by identity