REST API design

When two systems need to talk over the web, they need a shared set of conventions — otherwise every integration becomes a bespoke negotiation. REST (Representational State Transfer) is the most widely adopted style for designing such interfaces. It is not a standard you install but a set of principles that, when followed, make an API predictable, scalable, and pleasant to consume. Its central insight is to lean on the existing machinery of HTTP rather than inventing new conventions on top of it.

Resources are nouns

The first principle is that an API exposes resources — the “things” your system manages, like users, orders, or articles. Each resource is identified by a URL, and crucially, those URLs are nouns, not verbs. You write /users or /users/42, never /getUser or /deleteUserById.

This feels strange at first if you are used to naming functions, but it pays off. By keeping the URL a stable noun, you let the HTTP method supply the verb. The same path /users/42 can be read, replaced, or removed depending on which method hits it. This separation keeps the API surface small and consistent.

There are two flavours of resource URL. A collection like /users represents many resources, while an item like /users/42 represents one specific member of that collection. Operations on a collection (listing, creating) differ naturally from operations on an item (fetching, updating, deleting one).

Verbs map to CRUD

The four basic data operations — Create, Read, Update, Delete, known as CRUD — map cleanly onto HTTP methods:

The distinction between PUT and PATCH is worth pinning down. PUT replaces the entire resource with the representation you send, while PATCH applies a partial update, changing only the fields you provide. PUT is idempotent; PATCH may or may not be.

Speak in status codes

A well-designed REST API uses HTTP status codes honestly to communicate outcomes. A successful read returns 200 OK. A successful creation returns 201 Created, ideally pointing to the new resource’s location. A request for something that does not exist returns 404 Not Found, and a malformed request returns 400 Bad Request. Returning 200 for everything and burying the real outcome in the body is a common anti-pattern that defeats the purpose of using HTTP.

Statelessness and idempotency

REST inherits statelessness from HTTP and treats it as a virtue. Each request must carry everything the server needs to process it — there is no stored session that the next request relies upon. Authentication, for instance, travels in each request as a token in the Authorization header. The payoff is scalability: because no request is tied to a particular server’s memory, any server in a pool can handle any request, and you can add capacity simply by adding machines.

Idempotency is the close companion of statelessness. A method is idempotent if making the same call twice has the same effect as making it once. GET, PUT, and DELETE are idempotent; POST generally is not.

Idempotency is not academic trivia — it is what makes reliable clients possible. If a network failure leaves a client unsure whether its DELETE succeeded, it can safely retry, because deleting an already-deleted resource changes nothing further. Retrying a POST, by contrast, risks creating a duplicate, which is why creation endpoints sometimes need extra safeguards like idempotency keys.

Designing for change and scale

Two practical concerns round out good REST design. First, versioning: APIs evolve, and breaking changes would shatter existing clients. Introducing a version — commonly in the path like /v1/users, or in a header — lets new and old behaviour coexist so clients migrate on their own schedule.

Second, large collections need taming. Returning ten thousand users in one response is wasteful, so REST APIs use query parameters for filtering, sorting, and pagination — fetching results in manageable pages. Some APIs go further and embed hypermedia links in responses, pointing clients to related resources and available next actions so they can navigate the API by following links rather than hardcoding every URL.

Taken together, these principles turn an API from an idiosyncratic contract into something a newcomer can largely predict. That predictability is REST’s quiet superpower: when an API behaves the way the conventions say it should, consuming it becomes almost boring — which, for an integration, is exactly what you want.