REST API Design in 2026: A Full Engineering Reference

REST API design in 2026 is no longer a matter of taste — much of what used to be argued in style guides now has a published standard, a production reference implementation, or both. The hard part is that the consensus moved while a lot of shipped code stayed put. This reference pulls the current state of the art into one place.

Three things are true at once. The patterns that matter — structured errors, cursor pagination, idempotency keys, header-based versioning, machine-readable deprecation — are well-specified and battle-tested at companies like Stripe, GitHub, and Google. Most real-world APIs still don’t use them. And the gap between the two is exactly where developer experience, reliability, and integration cost quietly leak away.

What follows is organised the way an engineering team actually makes decisions: resource modelling, error format, pagination, idempotency, versioning, rate limiting, deprecation, and the OpenAPI-first workflow that ties it together. Every fact below is sourced from the relevant IETF RFC or the public engineering documentation of the provider it describes.

The first design decision is also the one teams most often get backwards: a REST resource is a noun in your domain model, not a row in your schema. Microsoft’s Azure REST API design guidance is explicit on this — use plural nouns for collection URIs, keep URI depth to a collection/item/collection maximum, and avoid APIs that mirror the internal database structure. Leaking your table names into the URL couples consumers to your storage layer and widens the attack surface for no benefit.

Google’s AIP-190 naming standard adds the conventions that keep a large API surface coherent: method names in VerbNoun UpperCamelCase, correct American English spelling, and the same term used for the same concept everywhere. It warns against overly generic words — instance, info, service — that create ambiguity. Google-style APIs also use a colon separator for custom actions on collections, making the action-versus-resource boundary explicit: POST /v1/videos:process rather than /processVideo. The standard methods stay List, Get, Create, Update, and Delete.

Here is the adoption gap in one line: the IETF has had a machine-readable error standard since 2023, and most APIs still return {"error": "something went wrong"}. RFC 9457, “Problem Details for HTTP APIs,” was published in July 2023 and supersedes RFC 7807. It defines a standardised JSON (and XML) error format served as application/problem+json, built from five base fields: type, title, status, detail, and instance.

RFC 9457 added three improvements over 7807: a registry for commonly-used problem type URIs to enable interoperability, clarified handling of multiple simultaneous problems, and expanded guidance for non-dereferenceable type URIs. One subtlety catches teams off guard — the detail field is explicitly for helping the client resolve the issue, not for server debugging output. Extension members beyond the five standard fields are allowed, and consumers must ignore unrecognised extensions so the format stays forward-compatible.

The practical migration is small and high-leverage. Swap a bare {"error": "not found"} for a problem+json body with a stable type URI and a client-actionable detail, set the Content-Type to application/problem+json, and your consumers get errors they can branch on programmatically instead of string-matching prose. It is one of the cheapest developer-experience upgrades an existing API can make.

Offset pagination feels free because it is, until your dataset isn’t small. The mechanism is the problem: offset-based pagination forces the database to scan and discard the first N rows on every query, so OFFSET 100,000 requires the engine to read and throw away 100,000 rows before returning a single result. At scale that cost grows roughly with how deep into the dataset the request reaches.

Cursor-based pagination avoids the problem by keying off a stable identifier — a timestamp or an opaque token — so the database can seek directly to the slice it needs. The trade-off is real and worth stating plainly: API consumers can no longer jump to an arbitrary page, because random access is lost, and cursors can be invalidated if records are deleted, which means fresh cursors with each response. GitHub’s production answer is to expose pagination through Link headers — containing next, last, first, and prev references — rather than baking URLs into the JSON body, and to have clients follow those links rather than construct query strings by hand.

Networks fail mid-request, and a client that doesn’t know whether its POST succeeded will retry. Idempotency keys make that retry safe. Stripe’s widely-copied spec uses an Idempotency-Key request header, recommends a V4 UUID, caps key length at 255 characters (vendor-stated), and retains keys for at least 24 hours (vendor-stated). It applies to all POST requests. Stripe saves the resulting status code and body of the first request regardless of whether it succeeded or failed — including 500 errors — and if the parameters on a retry don’t match the original request, the idempotency layer returns an error, preventing accidental reuse of a key for a different payload.

The reason this matters is fundamental to distributed systems, and Stripe’s own engineering writing puts it well — when a client sees a failure it can converge its state with the server’s by retrying until it verifiably succeeds, but only if the server makes that retry safe. Idempotency keys are how you keep the promise. If you’re building event-driven systems on top of this, the same discipline extends to idempotency patterns for webhooks and retries, where at-least-once delivery makes the property non-negotiable.

The version-numbering debate misses the real engineering question: how do you isolate a breaking change from the clients that aren’t ready for it? Stripe’s answer is date-based API versioning — values like 2017-05-25 rather than integer v1/v2 — and the company reports having shipped approximately 100 backwards-incompatible versions since 2011. New accounts are pinned to the latest version automatically at their first API call. The architecture underneath is a transformation layer: a core that only speaks the current version, plus version-change modules that convert responses backwards for older clients, which eliminates the version-check conditionals that would otherwise sprawl across business logic.

GitHub takes the header route, using an X-GitHub-Api-Version request header rather than URL-path versioning. Both keep the base URL stable, which is what makes them “soft” isolation. The comparison below puts the common strategies side by side on the dimensions that actually drive the decision.

A 429 Too Many Requests response is only half a design. RFC 9110 (Section 10.2.3) and RFC 6585 both recommend including a Retry-After header with the 429, where the value can be either an HTTP date or a delay in seconds. Without it, every client has to guess when to come back. On the client side, exponential backoff with jitter is the standard for recovery — and the jitter is not optional. Without it, multiple clients that hit the limit at the same moment will retry simultaneously, re-synchronise their traffic, and destabilise the server they were trying to be gentle with.

Good APIs let clients avoid the 429 entirely. Most providers expose X-RateLimit-Remaining and X-RateLimit-Reset headers so a proactive client can self-throttle before it trips the limit, rather than reacting after the fact. GitHub adds a nice twist for conditional requests: it returns ETag and Last-Modified headers, and a conditional GET using if-none-match or if-modified-since that returns 304 Not Modified does not consume primary rate-limit quota. On the implementation side, Redis is the standard backend for real-time rate limiting thanks to its atomic increments and TTL support.

Authentication sits alongside rate limiting as the other transport concern that shapes the whole API. OAuth 2.0 with PKCE (Proof Key for Code Exchange) is the standard auth flow for modern public clients; bearer tokens should expire in roughly 15 to 60 minutes with refresh token rotation, and every authentication pattern is exposed without HTTPS/TLS at the transport layer. For the algorithm-level view of how the limits themselves are computed, see our companion reference on rate limiting strategies for REST APIs.

Retiring an endpoint is a contract event, and the IETF has given it two machine-readable signals. RFC 8594 defines the Sunset HTTP response header, indicating the date and time after which a URI is expected to become unresponsive. Its companion, RFC 9745 (“The Deprecation HTTP Response Header Field”), defines the Deprecation header, which signals that an endpoint is deprecated. Used together, they let consumers detect and monitor deprecations automatically rather than discovering them when something breaks.

Standards describe the mechanism; policy is what makes deprecation humane. The widely-referenced open-source Zalando RESTful API Guidelines specify that deprecated endpoints must carry both the Deprecation and Sunset headers, and that teams owe consumers six to twelve months of notice plus a migration guide before decommissioning. The headers tell a machine; the notice period and the guide tell the engineers on the other end.

Every pattern above is only as trustworthy as the document that describes it — and a spec written after the code drifts away from reality the moment the code changes. The design-first answer is to make the OpenAPI specification the contract, not the implementation. OpenAPI 3.1.0 aligns fully with JSON Schema Draft 2020-12, added webhooks as a top-level element, made path items optional for reusable component libraries, and allowed descriptions alongside $ref usage. The current 3.1-line schema is 3.1.2 (schema updated 2025-11-23).

OpenAPI 3.2.0, released in September 2025, added structured tag navigation, streaming-friendly media types, and new OAuth flows while remaining fully backwards-compatible with 3.1. With the spec as the source of truth, code generation closes the drift gap: the open-source OpenAPI Generator produces client SDKs and server stubs across 50+ languages from a single OpenAPI document and integrates into CI/CD pipelines so generated code stays in sync with spec changes. When the spec is the contract, the generated client is correct by construction.

One more design lever belongs in the same conversation. HATEOAS — Hypermedia as the Engine of Application State — enriches responses with discoverable links to reduce client-server coupling, commonly serialised as HAL or JSON:API. In 2025–2026 it earns its complexity more for intricate client-server ecosystems such as workflow APIs and multi-step state machines than for simple CRUD. If you’re weaving APIs together across services, our reference on API-first development and microservices architecture picks up where this leaves off, as does our guide to serverless deployment for API backends.

Most API problems aren’t exotic; they’re the same handful of anti-patterns repeated across teams. Each one trades a small upfront convenience for a recurring tax on the consumers and on your future self. The grid below collects the ones worth auditing for first.