Designing REST APIs That Survive Real-World Clients

Tim Rabbetts | November 22, 2026

A REST API can look simple from the outside: a client sends an HTTP request, the server returns a response, and both sides exchange JSON. The difficult part is not making the first request work. It is designing an interface that remains understandable when clients retry requests, caches serve old representations, two users edit the same resource, permissions change and the API needs to evolve without breaking existing integrations.

REST is an architectural style rather than a requirement to expose database tables through JSON. Its useful constraints include identifying resources, manipulating them through representations, using self-descriptive messages and taking advantage of a uniform interface. Those constraints are intended to improve scalability, independent deployment and the ability to place intermediaries such as caches between clients and servers. ([ics.uci.edu](https://ics.uci.edu/~fielding/pubs/dissertation/abstract.htm?utm_source=openai))

This guide focuses on the decisions that make a REST API dependable in production. The examples use an imaginary support-ticket service, but the principles apply equally to public APIs, internal services and headless content platforms.

Start with resources, not controller actions

A resource is something a client can identify and retrieve or manipulate. In a support system, likely resources include tickets, users, comments and attachments. A resource should have a stable URI:

GET /tickets/1842
GET /tickets/1842/comments
GET /users/27

This is generally easier to understand than action-shaped endpoints such as /getTicket, /closeTicket and /addComment. The HTTP method expresses the broad operation, while the URI identifies the target.

That does not mean every operation must be forced into a simplistic CRUD model. Some domain operations are genuinely commands. If closing a ticket has important business rules, an endpoint such as POST /tickets/1842/closure-requests can model the creation of a closure request as a resource. Alternatively, POST /tickets/1842/actions/close may be appropriate for an explicitly command-oriented interface. The important point is to make the domain meaning visible rather than hiding it behind an arbitrary controller name.

Use nouns carefully

  • Use plural collection names such as /tickets and singular identifiers such as /tickets/1842.
  • Keep hierarchy meaningful. /tickets/1842/comments communicates ownership; avoid deeply nested paths that become difficult to query.
  • Do not expose implementation details such as database table names or internal numeric sequences unless they are part of the public contract.
  • Choose identifiers that are stable. Changing a slug or moving a record should not silently change the identity of the resource.

Resource modelling is also a security decision. A predictable identifier is not an authorisation check. If a client can request /tickets/1843, the server must still verify that the authenticated principal is allowed to view that ticket. Never treat an unguessable UUID as a replacement for access control.

Give HTTP methods their proper meaning

HTTP methods are not interchangeable verbs for invoking PHP, JavaScript or controller functions. Their semantics affect caching, retries, browser behaviour and intermediary components.

  • GET retrieves a representation and should not request a state change.
  • POST submits data for processing, commonly creating a subordinate resource or initiating a domain operation.
  • PUT replaces the selected resource representation, or creates it at a known URI where the API supports that behaviour.
  • PATCH applies a partial modification when the API defines the patch format and its semantics clearly.
  • DELETE removes the selected resource, or applies the API's documented deletion policy.
  • HEAD provides response metadata without the response body and can be useful for checking availability or representation metadata.

HTTP defines GET, HEAD, OPTIONS and TRACE as safe methods. It defines safe methods, PUT and DELETE as idempotent: repeating an identical request should have the same intended server effect as making it once. This is why clients can usually retry a failed PUT more confidently than a POST. ([rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9110.html?utm_source=openai))

Idempotent does not mean that every response will be identical. A DELETE may return 204 No Content the first time and 404 Not Found later, depending on the contract. It means the requested state transition is not multiplied merely because the request was repeated.

Be explicit about replacement and partial updates

One common API defect is calling an endpoint PUT while implementing merge-like behaviour. If omitted fields retain their old values, document that as a partial update or use PATCH. For a replacement request, make the representation complete enough for the server to calculate the new state:

curl -X PUT https://api.example.test/tickets/1842 \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"title":"Printer unavailable","priority":"high","status":"open"}'

For a patch format, define whether the payload is a merge document or an operation list. A merge-style payload might be:

{
  "priority": "high"
}

Do not make clients guess whether null means “clear this field”, “leave it unchanged” or “the value is unknown”. Define the rule and test it.

Design response contracts, not just endpoints

A useful response tells the client what happened and provides enough information to continue. For a successful ticket retrieval, return a representation with stable field names and predictable types:

{
  "id": "1842",
  "type": "ticket",
  "attributes": {
    "title": "Printer unavailable",
    "status": "open",
    "priority": "high",
    "created_at": "2026-11-22T09:14:00Z"
  },
  "links": {
    "self": "/tickets/1842",
    "comments": "/tickets/1842/comments"
  }
}

The exact envelope is a design choice. What matters is consistency. If one endpoint returns dates as ISO 8601 strings and another returns Unix timestamps, every client pays the cost. Define nullability, precision, enum values, maximum lengths and whether unknown fields may be added.

Use status codes as part of the contract rather than returning 200 OK for every outcome:

  • 200 OK for a successful retrieval or update that includes a representation.
  • 201 Created when a request creates a resource, normally with a Location header identifying it.
  • 202 Accepted when processing has started but is not complete. Return a way to check the operation rather than pretending it has finished.
  • 204 No Content when the operation succeeded and no response representation is needed.
  • 400 Bad Request when the request cannot be parsed or fails basic syntax rules.
  • 401 Unauthorized when the request lacks valid authentication credentials.
  • 403 Forbidden when the caller is authenticated but not allowed to perform the operation.
  • 404 Not Found when the resource does not exist, subject to the API's policy for hiding protected resources.
  • 409 Conflict when the request conflicts with the current state.
  • 412 Precondition Failed when a supplied conditional request header is not satisfied.
  • 422 Unprocessable Content when the syntax is valid but the submitted values fail domain validation.
  • 429 Too Many Requests when rate limits apply.
  • 5xx for failures that are genuinely on the server side.

HTTP status codes are grouped by their first digit, and clients must understand the class even if they do not recognise a particular code. A consistent status strategy lets generic clients handle errors safely while still allowing the response body to provide useful detail. ([rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9110.html?utm_source=openai))

Return machine-readable errors

Human-readable messages are useful for logs, but clients need stable fields for decisions. RFC 9457 defines a standard problem-details format for reporting HTTP API errors. A response could look like this:

{
  "type": "https://api.example.test/problems/validation-error",
  "title": "Request validation failed",
  "status": 422,
  "detail": "The ticket could not be updated.",
  "instance": "/requests/7f8c",
  "errors": [
    {
      "field": "priority",
      "code": "unsupported_value",
      "message": "Use low, normal or high."
    }
  ]
}

Use a stable error type or code for programmatic handling. Do not require clients to parse the English wording of detail. Also avoid returning stack traces, SQL fragments, access tokens or internal hostnames in error responses.

Validate at the boundary

Validate incoming data before it reaches domain services or persistence. Check content type, body size, required fields, data types, allowed values, string lengths and relationships between fields. For example, a ticket marked resolved might require a resolution note.

Validation should be repeated on the server even when the client has a schema generated from OpenAPI or another contract. Client-side validation improves usability; it does not establish trust. Treat every request as untrusted, including requests from your own front end.

Normalise carefully. Converting an email address to lowercase may be appropriate for comparison, but silently trimming or rewriting arbitrary user content may lose data. Record the final value returned by the API so clients know what the server accepted.

Prevent lost updates with conditional requests

Consider two agents editing the same ticket. Agent A reads version one, agent B reads version one, agent A saves changes, then agent B saves an older representation and unintentionally overwrites A's work. This is a concurrency problem, not merely a user-interface problem.

Return an ETag representing the current representation or version:

HTTP/1.1 200 OK
ETag: "ticket-1842-v7"
Content-Type: application/json

Require the client to send that value with an update:

curl -X PATCH https://api.example.test/tickets/1842 \
  -H 'If-Match: "ticket-1842-v7"' \
  -H 'Content-Type: application/merge-patch+json' \
  --data '{"priority":"high"}'

If the resource has changed, return 412 Precondition Failed rather than overwriting the newer representation. This gives the client an opportunity to reload, merge or ask the user to resolve the conflict.

The same validators also support efficient reads. A client can send If-None-Match; if the representation is unchanged, the server can return 304 Not Modified without sending the body again. HTTP caching specifications define entity tags and conditional requests for this purpose. ([rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9111.html?utm_source=openai))

Make collections usable at scale

Returning every ticket in one response works until the collection becomes large. Define pagination before consumers depend on an unbounded endpoint. Offset pagination is easy to understand:

GET /tickets?limit=50&offset=100&status=open

It can become inefficient or unstable when rows are inserted or deleted between requests. Cursor pagination is often better for changing collections:

GET /tickets?limit=50&after=eyJpZCI6MTg0Mn0

Define a deterministic sort order, return the next cursor only when another page exists and impose a maximum page size. Treat cursors as opaque: clients should store and resend them, not decode or construct them.

Filtering, sorting and searching also need limits. Allow only documented fields and operators. An unrestricted query language can expose sensitive fields, create expensive database plans or become an injection route. Set timeouts and consider rejecting requests that combine too many costly filters.

Use caching deliberately

Caching can reduce latency, bandwidth and origin load, but an incorrect cache policy can disclose one user's data to another. Publicly cache only responses that are safe to share. Responses containing user-specific or confidential data should generally use appropriate private or no-store directives.

For a public resource that may be reused for one minute, the response might include:

Cache-Control: public, max-age=60
ETag: "catalog-v31"

For an authenticated response that should not be stored by shared caches:

Cache-Control: private, no-store

Be precise about the cache key. If the representation varies by language, encoding or another request header, use Vary appropriately. Test caching through the actual reverse proxy or CDN rather than assuming that an origin response header alone proves the behaviour.

Build security into the resource model

Use HTTPS everywhere outside a deliberately isolated local development environment. Authenticate the caller, then authorise every operation against the specific resource and action. “The user has the editor role” is not enough if the editor may modify only tickets belonging to one organisation.

  • Prefer short-lived access tokens and protect refresh tokens as credentials.
  • Do not put bearer tokens in URLs, because URLs can appear in browser history, proxy logs and analytics.
  • Apply rate limits to authentication, expensive searches and mutation endpoints.
  • Limit request body sizes and reject unexpected content types.
  • Prevent mass assignment by maintaining an allow-list of writable fields.
  • Return the minimum data needed by the caller; do not serialise internal database objects wholesale.
  • Log authentication decisions, authorisation failures, request identifiers and resource identifiers without logging secrets or sensitive payloads.

Object-level authorisation, unrestricted resource consumption, security misconfiguration and unsafe consumption of other APIs are among the risks covered by the OWASP API Security Top 10. Use it as a review checklist, not as a substitute for threat modelling. ([api-security.owasp.org](https://api-security.owasp.org/editions/2023/en/0x04-release-notes/?utm_source=openai))

Design for retries and asynchronous work

Networks fail after the server has received a request but before the client receives the response. For operations such as charging a card, sending an email or creating an order, a client retry can duplicate the side effect.

Support an idempotency key for operations where duplicate processing is harmful:

curl -X POST https://api.example.test/payments \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Idempotency-Key: 9b2b5e0e-4c50-4a14-a7aa-3bdb7a3e7d52' \
  -H 'Content-Type: application/json' \
  --data '{"order_id":"ord_1842","amount":4999,"currency":"GBP"}'

The server should associate the key with the authenticated caller and a request fingerprint, store the result for a defined period and return the original result for a safe retry. If the same key is reused with different parameters, reject it rather than silently changing its meaning.

For long-running work, return 202 Accepted and a status resource:

HTTP/1.1 202 Accepted
Location: /operations/op_72c1

The operation resource can expose pending, running, succeeded or failed, together with a safe error representation. This is more honest and more operationally useful than holding an HTTP connection open until a background job finishes.

Version contracts by compatibility, not habit

Breaking changes include removing fields, changing a field's type, altering authentication requirements, changing the meaning of an enum or making a previously optional field mandatory. Adding a response field is usually compatible, but clients should ignore unknown fields rather than failing strict deserialisation.

Prefer additive evolution where possible. Introduce a new field, support both old and new values during a migration, measure usage and remove the old contract only after communicating a timetable. If a breaking version is unavoidable, choose a clear policy such as a versioned media type or a versioned URI. Do not mix several informal version schemes across the same API.

Document deprecations in responses where useful, publish migration guidance and keep contract tests for representative clients. An OpenAPI document can describe the surface of an API, but it does not automatically prove that authorisation, concurrency and error behaviour are correct.

Make production behaviour observable

Every request should be traceable without exposing secrets. Generate or propagate a request identifier and include it in the response. Record method, route template, status, duration, response size, authenticated principal or service identity, and a safe outcome classification.

Monitor more than average latency. Track error rates by route and status class, timeout rates, throttling, cache hit ratio, database time, queue delay and payload sizes. A fast endpoint that frequently returns retries or stale data is not healthy.

Test the contract at several levels:

  1. Unit-test validation, policy and domain rules.
  2. Integration-test persistence, transactions, queues and authentication middleware.
  3. Contract-test status codes, headers, error shapes and representation compatibility.
  4. Load-test realistic collection queries, pagination and cache behaviour.
  5. Run security tests for broken object-level authorisation, mass assignment, injection and rate-limit bypasses.
  6. Test failure paths, including client timeouts after the server commits a mutation.

A practical review checklist

  • Can a new developer predict the URI and method for each common operation?
  • Are safe and idempotent operations implemented according to their HTTP semantics?
  • Does every mutation have clear validation and authorisation rules?
  • Can clients distinguish validation, authentication, permission, conflict and server failures?
  • Are errors stable for machines and useful for people?
  • Are lost updates prevented with versions or conditional requests?
  • Are collection limits, sorting and pagination explicit?
  • Could a shared cache accidentally serve private data?
  • Can unsafe operations be retried without duplicating side effects?
  • Can the team evolve the contract without surprising existing clients?
  • Do logs and metrics explain what happened without recording credentials or sensitive content?

The best REST APIs are not defined by how closely they imitate a textbook diagram. They are successful because their resources, methods, representations and failure modes remain predictable under real network conditions. Start with the domain, respect HTTP semantics, make concurrency and caching explicit, enforce authorisation at the resource boundary and treat observability as part of the contract. Those decisions produce an API that clients can safely use today and that your team can still change tomorrow.