REST APIs Explained: Resources, Methods, and Conventions

We've established that an API is a contract with endpoints. Now: how do you organize those endpoints sensibly? By far the most common answer is REST — a style for designing APIs over HTTP. REST isn't a strict protocol so much as a set of conventions, and its whole value is that, once learned, an API built this way is predictable.

Everything is a resource

REST's central idea is to model your system as resources — the "things" your application is about: users, orders, articles, comments. Each resource gets a URL that identifies it:

Notice the URLs are nouns. They name things, not actions. This is the most common REST mistake to avoid:

Methods map to operations

REST leans directly on HTTP's methods to act on resources, which gives you a clean, complete vocabulary for the common operations (often called CRUD — create, read, update, delete):

Because these methods carry the safety and idempotency guarantees from HTTP, a RESTful API behaves predictably with browsers, caches, and proxies — a GET can be cached, a failed DELETE can be safely retried.

Predictability is the real payoff

Here's why REST won. Once you know an API is RESTful and you've seen GET /users/42, you can guess the rest: there's probably a GET /users, a POST /users, a DELETE /users/42. The conventions make the whole API discoverable from a single example.

That consistency lowers the cost of every integration. Developers spend less time reading docs because the shape is familiar. An API that invents its own ad-hoc structure for every endpoint forfeits this entirely.

Statelessness and status codes

REST inherits two things straight from HTTP, and uses both deliberately:

• Stateless requests. Each call carries everything needed to handle it, including authentication. The server holds no per-client memory between requests — which, as in the HTTP chapter, is what lets any server handle any request and makes the API easy to scale.
• Meaningful status codes. A RESTful response uses the status code to report the outcome: 201 Created after a POST, 404 Not Found for a missing resource, 400 Bad Request for bad input, 401/403 for auth problems. Clients react to the code, not by parsing prose.

Using status codes properly is part of the contract: it lets callers handle success and failure programmatically instead of guessing.

REST is a style, not a law

A useful dose of realism: REST is a set of conventions, not a specification you can violate and get arrested for. Real-world APIs bend the rules constantly — adding a /search endpoint, batching operations, or shaping responses for a specific client — and that's fine. The purists' checklist matters far less than the goal it serves: a clean, consistent, predictable interface.

When you're unsure, optimize for the developer who'll use your API: would they find this endpoint guessable and obvious? That instinct will serve you better than any purity score. REST's competitor, GraphQL, takes a very different approach to the same goal — and seeing the contrast sharpens your sense of when each fits.

Recap

• REST models your system as resources, each identified by a URL.
• Use nouns in the path (/users/42) and let HTTP methods supply the verb (GET, POST, PUT/PATCH, DELETE).
• The payoff is predictability — known conventions make the whole API guessable from one example.
• REST is stateless and speaks in status codes, so clients can react to outcomes programmatically.
• It's a style, not a law — bend the rules for a cleaner, more predictable interface when it helps.

REST shines for resource-style APIs, but it struggles when clients need flexible, precise data. A different approach — GraphQL — tackles exactly that. Continue to GraphQL Explained.