Web & Backend
REST APIs
REST (Representational State Transfer) is a set of conventions, not a formal protocol or standard: it says to model server-side data as resources addressed by URLs, manipulate them with standard HTTP methods, and represent them in a portable format such as JSON. There is no single body that certifies an API as REST-compliant, which is why 'RESTful' in practice covers a wide range of APIs, from ones that follow the conventions closely to ones that are really just JSON-over-HTTP with REST vocabulary borrowed for the endpoint names.
Why it matters
- It's the default shape of most public and internal HTTP APIs
- Payment processors, cloud providers, and most internal microservices expose REST-shaped endpoints, so reading and designing one is a routine skill, not a specialty.
- It piggybacks on HTTP's existing infrastructure
- Because GET requests are cacheable by design, a REST API can be cached by a CDN or browser with no extra protocol on top, unlike an API that always POSTs.
- It's easy to explore and debug with generic tools
- curl, a browser address bar, or Postman can poke at a REST endpoint with no special client library, which lowers the bar for both building and consuming one.
- It's the baseline other API styles are usually explained against
- GraphQL and gRPC are most often introduced by contrast with REST's trade-offs, so understanding REST first makes those comparisons make sense.
Resources, verbs, and a request
A resource is a noun — an order, a customer, a document — addressed by a URL like /orders/42. The HTTP method says what to do to it: GET reads, POST creates (often at a collection URL like /orders), PUT or PATCH updates, DELETE removes. The response's status code and body report what actually happened, and a well-designed API keeps that mapping consistent across every endpoint rather than inventing one-off conventions per route.
POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
{"customerId": 42, "items": [{"sku": "ABC-1", "qty": 2}]}
HTTP/1.1 201 Created
Location: /orders/1009
Content-Type: application/json
{"id": 1009, "status": "pending"}What 'RESTful' means in practice
Fielding's original description includes constraints most real APIs only partly follow — statelessness (each request carries everything needed to understand it) is common, but HATEOAS (responses containing links to the next valid actions, so a client discovers the API rather than hardcoding URLs) is rare in practice. Most APIs that call themselves REST are really 'resource-oriented JSON over HTTP': a genuinely useful and common style, just not a strict implementation of the original constraints.
Status codes, pagination, and versioning
A consistent API uses status codes honestly (404 for a missing resource, 422 or 400 for bad input, 409 for a conflict) so clients can branch on them without reading the body. Endpoints that return lists need a pagination convention (a cursor or a page/limit pair) so a large table doesn't come back as one enormous response. Versioning — whether in the URL path, a header, or not at all until a breaking change forces it — is one of the least standardized parts of REST API design, and every large API handles it a little differently.
Mistakes people make here
- Putting verbs in the URL, like /getUser or /createOrder
- This turns the URL back into an RPC-style function call and duplicates what the HTTP method is already supposed to say — GET /users/42 already means 'get the user', so /getUser/42 says the same thing twice, inconsistently.
- Returning 200 for every response regardless of outcome
- It pushes all error handling into parsing the body on every single call, and breaks any generic tooling (monitoring, caching, retry middleware) that relies on the status code meaning what it's supposed to mean.
- Never versioning the API and shipping breaking changes in place
- Any client already depending on the old response shape breaks the moment a field is renamed or removed, with no way to opt in gradually — a version marker, even a simple one, buys a migration window.
- Designing endpoints around the database schema instead of the client's actual needs
- It's the quickest way to build an API, but it usually means the client has to make several calls and stitch data together itself, or the server ends up bolting on ad hoc extra endpoints later.
Strengths and trade-offs
Where it is strong
- A simple, widely understood mental model: nouns as URLs, verbs as HTTP methods.
- Naturally cacheable, since GET requests fit HTTP's existing caching machinery without extra work.
- Broad tooling support — every language, every HTTP client, every API testing tool works with it out of the box.
- Easy to document and explore incrementally, one endpoint at a time, without needing a client to understand a whole schema upfront.
The trade-offs
- Fixed response shapes mean over-fetching (getting fields you don't need) or under-fetching (needing several calls for related data) is common.
- Related resources often mean multiple round trips — fetching an order and its customer and its items can mean three separate requests.
- There's no enforced contract the way a GraphQL schema or a gRPC IDL provides, so clients and servers can drift out of sync silently.
- Versioning, pagination, and filtering conventions are ad hoc — every REST API tends to reinvent its own approach to each.
Who needs this
Core knowledge for any backend developer building an API and any frontend or mobile developer consuming one.
Questions about rest apis
- What's the difference between 'REST' and 'RESTful'?
- In practice they're used interchangeably to mean a resource-and-HTTP-verb style API. Strictly, 'REST' refers to Roy Fielding's full set of architectural constraints, and most APIs called 'RESTful' only follow some of them — statelessness and resource-oriented URLs are common, but things like HATEOAS rarely are.
- Do I need to implement HATEOAS to have a real REST API?
- No, not in practice. Very few production APIs implement it, and calling an API REST without it is standard industry usage, even though it technically falls short of Fielding's original definition.
- When should I reach for GraphQL instead of REST?
- When clients need very different slices of related data (a mobile app and a web dashboard pulling different fields from the same resources) and over-fetching or many round trips is a real, measured problem — not by default, since GraphQL adds real server-side complexity.
- Is REST becoming obsolete?
- No. It remains the default for public APIs and most internal services because of its simplicity and tooling support; GraphQL and gRPC solve specific problems REST has, but they haven't replaced it broadly.