REST (Representational State Transfer)
An architectural style for providing interoperability between computer systems on the internet.
Detailed Explanation
REST uses a stateless, client-server, cacheable communications protocol, most commonly HTTP. It treats data as 'resources' which are interacted with using standard verbs (GET, POST, etc.). Because it relies on existing web standards, it is highly scalable and is the most common way to build web APIs today.
Quick Summary
REST models APIs as resources (nouns) acted on with HTTP verbs. Most modern APIs are "REST-ish" , they use HTTP and JSON but don't follow the full theory; that's usually fine and pragmatic.
Key Takeaways
- Resources have URLs; verbs (GET, POST, PUT, PATCH, DELETE) describe what to do with them.
- Stateless: each request carries enough context (token, identifiers) to be processed on its own.
- HTTP status codes communicate outcome (200, 201, 400, 404, 409, 422, 500) , use them properly.
- Pagination, filtering, sorting are conventions, not standards; document them clearly.
- HATEOAS (the "hypermedia" purity REST originally required) is rarely implemented; few clients consume it.
When to use it
- Public web APIs (Stripe, GitHub, Twilio) where broad client compatibility matters.
- Microservices that benefit from HTTP-native tooling (caching, observability, gateways).
- Resource-shaped data models where CRUD maps naturally to HTTP verbs.
- Anywhere you want curl, browsers, and existing HTTP middleware to "just work."
Common Mistakes
- Verb-in-URL anti-patterns (`POST /createUser`); use `POST /users`.
- Returning 200 OK with `{ error: ... }` in the body , clients lose the ability to handle failure via standard HTTP semantics.
- PATCH bodies that are really PUTs (full replacements) , confusing for callers.
- Over-nesting URLs (`/users/123/orders/456/items/789`); flatten where possible.
REST (Representational State Transfer), Frequently Asked
REST or GraphQL?
REST when consumers are diverse and you control the data shapes , simple, cacheable, broadly understood. GraphQL when clients have varying needs and you can centralize query control. Both are valid; the question is who owns the API shape: the server (REST) or the client (GraphQL).
REST or gRPC?
REST for public APIs and external developer experience. gRPC for internal service-to-service traffic where performance and strongly-typed schemas matter. Many companies do both , REST at the edge, gRPC inside.