Skip to main content
REST API Best Practices Every Developer Should Know

REST API Best Practices Every Developer Should Know

KU
· Founder & Chief Editor
• 8 min read•Updated •

A practical guide to designing REST APIs that stay predictable, easy to consume, and safe as your service grows.

Key takeaways

  • Model REST APIs as plural-noun resources and use HTTP methods and status codes exactly as RFC 9110 defines them.
  • Return one structured error shape, such as RFC 9457 problem details, and paginate every collection with cursors.
  • Version only for breaking changes, and authorize every request on the server.

Build REST APIs around plural-noun resources, use HTTP methods and status codes the way RFC 9110 defines them, return one structured error shape, paginate every collection with cursors, and bump versions only for breaking changes. Applied consistently from the first release, those five conventions prevent most of the support tickets and migrations an API generates.

Verified against

HTTP semantics per RFC 9110, problem details per RFC 9457 (which obsoletes RFC 7807), and 429 per RFC 6585, against the rfc-editor.org texts. Checked October 2026.

A REST API is a contract. Once other teams build against it, every inconsistency becomes a support ticket and every breaking change becomes a migration. Most of what makes an API pleasant to use comes down to a handful of conventions applied consistently. These are the ones we get right from day one.

Resource-oriented URLs

Model your API around resources, not actions. A resource is a noun, and collections are plural.

code
GET  /orders            # list orders
GET  /orders/42         # a single order
GET  /orders/42/items   # items belonging to order 42

Avoid verbs in paths. /getOrders or /createOrder are RPC habits leaking into REST. The HTTP method already carries the verb, so let it. Keep hierarchy shallow. Nesting is useful for ownership (/orders/42/items), but past two levels it gets awkward, and you can usually flatten with query parameters instead.

Use HTTP methods for what they mean

Each method has defined semantics, and clients, proxies, and caches rely on them.

GET: read a resource, never causes side effects, safe and idempotent. POST: create a resource or trigger a process, not idempotent. PUT: replace a resource fully, idempotent. PATCH: update part of a resource, not guaranteed idempotent. DELETE: remove a resource, idempotent.

Idempotency matters more than it sounds. If a client retries a PUT or DELETE after a timeout, the result should be the same as sending it once. That property is what makes safe retries possible on flaky networks. For non-idempotent POST operations where duplicates are costly, support an Idempotency-Key header so the server can detect and collapse retries.

Return meaningful status codes

The status code is the first thing a client checks. Use it honestly.

200 OK: successful read or update. 201 Created: a new resource exists, include a Location header pointing to it. 204 No Content: success with nothing to return, common for DELETE. 400 Bad Request: the request is malformed or syntactically wrong. 401 Unauthorized: no valid credentials, the caller must authenticate. 403 Forbidden: authenticated, but not allowed to do this. 404 Not Found: the resource does not exist. 409 Conflict: the request clashes with current state, like a duplicate or a version mismatch. 422 Unprocessable Content: syntax is fine but the data fails validation. 429 Too Many Requests: rate limit hit, include a Retry-After header.

The distinction between 400 and 422 trips people up. Use 400 when you cannot parse the request at all, and 422 when you parsed it fine but a field violates a business rule. That difference tells the client whether to fix its serialization or fix its data. (RFC 9110 renamed 422 from "Unprocessable Entity" to "Unprocessable Content"; the number and meaning did not change.)

Consistent JSON and naming

Pick one casing and hold the line everywhere. snake_case or camelCase both work, but mixing them guarantees bugs on the consumer side. Use ISO 8601 for every timestamp, always in UTC, so there is no ambiguity about timezones or format.

JSON
{
  "id": 42,
  "status": "shipped",
  "total_amount": 79.90,
  "currency": "EUR",
  "created_at": "2026-08-08T14:03:00Z"
}

Keep field names stable. Renaming a field is a breaking change even if the data behind it is identical.

Structured error responses

Errors deserve the same care as success responses. A raw stack trace or a bare string helps nobody. Return a predictable shape with a machine-readable code, a human-readable message, and, for validation failures, the offending field.

JSON
{
  "error": {
    "code": "validation_failed",
    "message": "The request contains invalid fields.",
    "details": [
      {
        "field": "email",
        "code": "invalid_format",
        "message": "Must be a valid email address."
      }
    ]
  }
}

The code lets clients branch programmatically, the message goes in logs and UIs, and field lets a frontend highlight exactly what to fix. Keep the codes documented and stable, because clients will switch on them.

If you have no house format yet, use RFC 9457 problem details instead of inventing one. It defines the application/problem+json media type with type, title, status, detail and instance members, and lets you add extensions such as an errors array for field failures. Clients and gateways increasingly understand it out of the box.

Filtering, sorting, and pagination on collections

Any collection that can grow needs these controls. Use query parameters and never return an unbounded list.

code
GET /orders?status=shipped&sort=-created_at&limit=25&cursor=eyJpZCI6NDJ9

Cursor-based pagination holds up better than offset pagination under changing data, since offsets shift when rows are inserted or deleted. Return the next cursor and a total where it is cheap to compute. For a deeper look at the tradeoffs, see API pagination.

HATEOAS, in moderation

Hypermedia links let a response tell the client what it can do next, which reduces hardcoded URL assembly.

JSON
{ "id": 42, "status": "shipped",
  "_links": { "cancel": { "href": "/orders/42/cancel" } } }

Full HATEOAS is rarely worth the ceremony for internal APIs. A few relevant links on key resources give most of the benefit without forcing every client to become a hypermedia parser.

Versioning

Decide on versioning before you ship, not after the first breaking change. A version in the path (/v1/orders) is the most visible and cache-friendly option, and header-based versioning is cleaner but easier to overlook. Whatever you choose, additive changes like a new optional field should never require a version bump. Reserve new versions for changes that genuinely break existing clients.

Caching with ETag and Cache-Control

Caching cuts load and latency when you let it. Send Cache-Control to state how long a response stays fresh, and an ETag so clients can revalidate cheaply.

code
GET /orders/42
< ETag: "a1b2c3"
< Cache-Control: private, max-age=60

GET /orders/42
> If-None-Match: "a1b2c3"
< 304 Not Modified

A 304 skips the body entirely, which is a real bandwidth win on large or frequently polled resources.

Security basics

Serve everything over HTTPS, with no plaintext fallback. Authenticate with short-lived tokens (OAuth 2.0 bearer tokens or signed JWTs) rather than long-lived API keys where you can, and always authorize on the server per request. Never trust the client to enforce access. Rate-limit to protect against abuse and runaway clients, and validate every input server-side. Security is broad enough to warrant its own read, so see API security best practices for the full picture.

Checklist

  • URLs are plural nouns with shallow, ownership-based hierarchy
  • HTTP methods match their semantics, and idempotent methods are safe to retry
  • Status codes are specific, including 201, 204, 409, 422, and 429
  • JSON casing is consistent and timestamps are ISO 8601 UTC
  • Errors return a structured code, message, and field
  • Collections support filtering, sorting, and cursor pagination
  • Versioning strategy is decided and additive changes never break clients
  • ETag and Cache-Control are set on cacheable responses
  • HTTPS everywhere, tokens over static keys, authorization on every request

Questions people ask

Should I use 400 or 422 for validation errors?

Use 400 Bad Request when the server cannot parse the request at all: malformed JSON, a wrong content type, a missing required header. Use 422 Unprocessable Content when the body parses fine but a value breaks a rule, such as an email in the wrong format or an end date before the start date. The split tells the client whether its serializer or its data is wrong.

Is PATCH idempotent?

Not by definition. RFC 9110 lists GET, HEAD, OPTIONS, TRACE, PUT and DELETE as idempotent, and PATCH is not on that list. A JSON Merge Patch that sets fields to fixed values happens to be safe to repeat, but a patch that appends to an array or increments a counter is not. If clients will retry PATCH or POST, accept an Idempotency-Key header and deduplicate on the server.

Should the API version go in the URL or a header?

Put it in the path (/v1/orders) unless you have a strong reason not to. Path versions are visible in logs, easy to route at the gateway, and cache cleanly because the URL differs. Header or media-type versioning keeps URLs tidy but is easy for clients to forget and harder to debug. Either way, additive changes such as a new optional field should never need a new version.

The call we'd make

Get the conventions locked before the first client integrates, because consistency is far cheaper to establish than to retrofit. Start with resource URLs, honest status codes, and a structured error shape, since those three shape every other decision. Layer in pagination, caching, and versioning as the API grows. For the wider strategy behind all of this, our pillar on API design best practices ties the pieces together.

Sources

Explore topics:DevOps
React
Share this post
Cite this article
Plain text

Kiril Urbonas (2026). REST API Best Practices Every Developer Should Know. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/rest-api-best-practices

Markdown

[REST API Best Practices Every Developer Should Know](https://www.devopsness.com/blog/rest-api-best-practices) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)

KU

Kiril Urbonas

Founder & Chief Editor

608 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.