REST API
An application programming interface that conforms to the constraints of REST architectural style.
Detailed Explanation
REST (Representational State Transfer) uses standard HTTP verbs and status codes to interact with resources identified by URLs. It is stateless, meaning each request must contain all the information needed to process it. REST has been the dominant API architecture for over a decade due to its simplicity and broad compatibility across all programming languages.
Quick Summary
A REST API exposes resources (users, orders, posts) at URLs and manipulates them through HTTP verbs and standard status codes. It is stateless and cache-friendly, which is why it dominates public APIs even decades after Roy Fielding defined it.
Key Takeaways
- Resources, not actions, drive the URL design: /orders/42, not /getOrder?id=42.
- Statelessness means the server stores no client context between requests, auth and pagination state travel in the request itself.
- Uniform interface: same verbs, same status codes, same content negotiation across every endpoint.
- HATEOAS (hypermedia links in responses) is part of the original REST definition but is rarely implemented strictly.
- JSON is the de-facto wire format, but REST is format-agnostic, XML, CBOR, or Protobuf are all valid representations.
When to use it
- Public APIs where broad client compatibility matters more than payload efficiency (Stripe, GitHub, Twilio).
- CRUD-shaped backends where resources map cleanly onto HTTP verbs.
- Mobile and web apps that benefit from HTTP-layer caching and CDN edge support.
- Integrations and webhooks where consumers expect a familiar HTTP-style contract.
Common Mistakes
- Designing RPC-shaped endpoints (/api/createUser) and calling them REST, they work, but lose the cacheability and uniformity that make REST valuable.
- Returning 200 OK with an error payload instead of a 4xx/5xx status, breaks generic clients and monitoring.
- Putting verbs in URLs (/users/123/delete) instead of using the DELETE method.
- Ignoring pagination, filtering, and sorting until traffic grows, then bolting them on inconsistently per endpoint.
REST API, Frequently Asked
REST vs. GraphQL, which should I choose?
Choose REST when consumers are diverse, caching matters, and your data is resource-shaped. Choose GraphQL when a single client needs to fetch deeply nested data in one round trip or when many clients each want different subsets of the same data.
Does REST require JSON?
No. REST is a set of architectural constraints, not a data format. JSON is the most common representation, but XML, MessagePack, and Protobuf are all compatible with REST.
Is REST outdated?
No, it powers the vast majority of public APIs. GraphQL, gRPC, and tRPC are alternatives for specific use cases, but REST remains the default choice when broad reach, CDN caching, and simple tooling matter.