What is REST API?
Definition
A REST API is a web API designed around the principles of REST (Representational State Transfer), an architectural style defined by Roy Fielding. Data is modeled as resources identified by URLs and manipulated with standard HTTP methods such as GET, POST, PUT, PATCH and DELETE. Each request is self-contained, the server keeps no client session state between requests, and outcomes are reported with HTTP status codes, usually with JSON payloads.
Also known as: RESTful API, REST, Representational State Transfer
An architectural style, not a protocol
REST was described by Roy Fielding in his 2000 doctoral dissertation. It introduces no new protocol; instead it sets out how to use what the web already has (URLs, HTTP methods, status codes, headers) under a set of constraints:
- Client-server: the user interface and data storage evolve independently.
- Stateless: every request carries everything the server needs to understand it, and the server stores no client session state between requests. That is why credentials travel with each request, for example as a JWT.
- Cacheable: responses state whether and for how long they may be cached.
- Uniform interface: resources are identified by URIs and changed through their representations (e.g. JSON), messages are self-descriptive, and responses can link to the next possible actions (HATEOAS).
- Layered system: the client does not need to know whether a proxy, load balancer or CDN sits in between.
- Code on demand: the server may send code for the client to run. This is the only optional constraint.
In practice, most services called “REST APIs” do not honor every constraint; HATEOAS in particular is rarely implemented. In industry usage the term mostly means a resource-oriented API that respects HTTP semantics and speaks JSON.
Resources and HTTP methods
In a REST design the URL names a thing, not an action. /orders/1042 fits the model; /getOrder?id=1042 does not, because it puts the verb in the URL. The verb is the HTTP method:
| Method | Purpose | Safe | Idempotent |
|---|---|---|---|
GET | Read a resource | Yes | Yes |
POST | Add a resource to a collection or trigger processing | No | No |
PUT | Replace a resource with the representation sent | No | Yes |
PATCH | Partially update a resource | No | Not guaranteed |
DELETE | Remove a resource | No | Yes |
A safe method is one that does not change data on the server. The semantics of each method are defined in RFC 9110, the HTTP standard.
Why idempotency matters
A request is idempotent if sending it once or several times in a row leaves the server in the same state. When a connection drops before the response arrives, the client cannot tell whether the request was processed. A PUT or DELETE can simply be retried; a retried POST may create a second order or charge a card twice. Critical POST endpoints such as payments therefore often use an idempotency key: the client sends a unique key per operation, and the server returns the original result instead of processing the same key again.
A request and its response
POST /v1/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: application/json
{"productId": "SKU-881", "quantity": 2}HTTP/1.1 201 Created
Location: /v1/orders/1042
Content-Type: application/json
{"id": 1042, "status": "pending", "total": "1499.90"}The server confirms with 201 Created that a new resource exists and gives its address in the Location header. The client can later read it with GET /v1/orders/1042.
Using status codes properly
A well-behaved REST API reports outcomes through HTTP status codes rather than burying them in the body:
200 OK,201 Created,204 No Content: success.400 Bad Request,422 Unprocessable Content: the client sent invalid data.401 Unauthorized: the caller is not authenticated;403 Forbidden: authenticated, but not allowed to do this.404 Not Found,409 Conflict: the resource does not exist, or the request clashes with its current state.429 Too Many Requests: a rate limit was hit.500and503: the problem is on the server side.
Returning 200 for everything and signalling failure with an "error": true field makes errors invisible to clients, proxies and monitoring tools alike.