REST API Patterns

REST API patterns are repeatable design decisions that make an HTTP API predictable. The most common ones are modelling resources instead of actions, using HTTP methods and status codes as defined, paginating collections, returning consistent errors, making retries safe with idempotency keys, versioning and deprecating deliberately, caching and rate-limiting, and publishing an OpenAPI description. This page walks through eight such patterns and links each to the standards, style guides and vendor documentation that define it.

Primary sources and public style guides behind the patterns below. The Level Up Coding article that prompted this page is a Medium member-only story, so this page links to it and builds its own pattern list from standards and published guidelines.

Name things, not operations. A URL identifies a resource, such as /orders or /orders/{id}, and the HTTP method says what to do with it, so avoid endpoints like /getOrders. Operations that do not fit create, read, update or delete are often modelled as a sub-resource or a state change.

Let each method keep its meaning: GET reads and is safe, POST creates or triggers processing, PUT replaces, PATCH changes part of a resource and DELETE removes it. Return status codes that say what happened, such as 201 with a Location header after creation and 404, 409 or 422 for client errors.

Never return an unbounded list. Cursor-based pagination stays stable when records are added or removed, while offset pagination is simpler but can skip or repeat items. Return the next page as a link, and expose filters and sort order as query parameters.

Use one error shape across the whole API so clients can handle failures generically. RFC 9457 defines a machine-readable problem details format with a type, title, status, detail and instance.

Networks fail, so clients retry. GET, PUT and DELETE are idempotent by definition, but POST is not, so APIs accept a client-supplied Idempotency-Key and return the original result when the same key arrives again.

Plan for change from the start. Version in the URL, in a header or by date, announce deprecation with the Deprecation header and give the removal date in a Sunset header.

Let clients and proxies reuse responses with Cache-Control and ETag validators, so unchanged data returns a cheap 304. Protect the service with rate limits that answer 429 Too Many Requests and tell clients when to retry.

Publish the API as a machine-readable contract. An OpenAPI description lists endpoints, parameters and schemas, and tools use it to generate documentation, client SDKs, mock servers and contract tests.

Related directories on this site.