Overview
REST (Representational State Transfer) is an architectural style for networked applications that uses HTTP methods to operate on resources identified by URIs. RESTful APIs model domain concepts as resources, use standard HTTP verbs (GET, POST, PUT, DELETE) for operations, and return representations (typically JSON) that clients can cache and navigate via hyperlinks. REST’s strength lies in its simplicity, ubiquity, and alignment with HTTP infrastructure — caches, load balancers, and CDNs work transparently. Well-designed REST APIs are self-describing, versioned, and follow consistent naming conventions.
Key Concepts
- Resources — Nouns, not verbs.
/users/123not/getUser?id=123. Resources map to domain entities or aggregates. - HTTP methods — GET (read), POST (create), PUT (replace), PATCH (partial update), DELETE (remove). Each has defined semantics and idempotency guarantees.
- Status codes — 2xx success, 4xx client error, 5xx server error. Use specific codes (201 Created, 404 Not Found, 409 Conflict) over generic 200/500.
- Content negotiation — Clients specify desired format via Accept headers. Servers respond with Content-Type.
- HATEOAS — Hypermedia as the Engine of Application State. Responses include links to related resources and available actions.
- Versioning — URL path (
/v2/users), header (Accept: application/vnd.api+json;version=2), or query parameter strategies. - Pagination — Cursor-based or offset-based for large collections. Include total count and navigation links.
Trade-offs
- Over-fetching and under-fetching require multiple round trips (addressed by GraphQL)
- HATEOAS is rarely implemented in practice despite being core REST
- Versioning strategy affects backward compatibility burden
- Not ideal for real-time or streaming use cases
Related
- GraphQL addresses REST’s over-fetching/under-fetching limitations
- API Design covers broader principles applicable to any API style
- Load Balancing works transparently with stateless REST APIs