How it works
In a REST API, resources live at URLs (/orders, /orders/42) and HTTP methods say what to do: GET reads, POST creates, PUT or PATCH updates, DELETE removes. Status codes report the result (200 OK, 404 Not Found) and bodies are usually JSON. Each request carries everything the server needs, such as a token, so any server in a group can answer it.
Roy Fielding described REST in 2000, and it became the default because it needs nothing beyond HTTP: browsers, phones, scripts and other servers can all call it, and CDNs can cache its responses. An OpenAPI document describes the endpoints and can generate docs and typed clients. The weak spot is fit: one screen may need several calls, or receive far more data than it uses.
REST API pros and cons
Pros
- Works with any language, tool or device that speaks HTTP
- Simple to understand, test and debug with a browser or curl
- Standard HTTP caching, status codes and tooling apply
- OpenAPI can generate documentation and typed clients
Cons
- Screens often need several requests or get more data than needed
- No built-in contract, so types and docs drift without OpenAPI
- Versioning and consistent naming take discipline
When to use REST API
Pick it when
- Public or partner APIs that anyone should be able to call
- Most app backends, especially with several kinds of client
- Straightforward create, read, update and delete on clear resources
Skip it when
- Many clients need very different slices of deeply linked data (consider GraphQL)
REST API vs the alternatives
Related terms
More in Backend and APIs
API styles