Backend

REST API

An architectural style for building web APIs that uses HTTP methods (GET, POST, PUT, DELETE) to perform CRUD operations on resources identified by URLs.

REST (Representational State Transfer) is an architectural style for designing web APIs. RESTful APIs use standard HTTP methods to perform operations on resources, making them intuitive and widely compatible.

Core principles include statelessness (each request contains all necessary information), uniform interface (consistent URL patterns and HTTP methods), resource-based (everything is a resource with a unique URL), and representation (resources can be represented in JSON, XML, etc.).

Standard HTTP method mapping: GET (read), POST (create), PUT/PATCH (update), DELETE (remove). Status codes communicate results: 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error).

REST API design best practices include using plural nouns for resources (/users, /posts), nesting for relationships (/users/123/posts), pagination for large collections, versioning (v1/users), and HATEOAS (including links to related resources in responses).

How it works

REST was defined by Roy Fielding in his 2000 doctoral dissertation as an architectural style: a set of constraints, not a protocol or a file format. The constraints are client-server, stateless, cacheable, uniform interface, layered system, and an optional sixth, code-on-demand.

Stateless means each request must contain all of the information needed to understand it; the server cannot rely on context stored from earlier requests. In practice the client sends its credentials, such as a bearer token, on every call, which also lets any server behind a load balancer handle any request.

The uniform interface is what makes REST APIs predictable. Resources are identified by URLs, clients change them by sending representations (usually JSON), messages are self-descriptive through their method, headers and media type, and hypermedia links in responses tell the client what it can do next.

HTTP methods carry agreed meanings defined in RFC 9110. GET, HEAD, OPTIONS and TRACE are safe, meaning read-only. GET, HEAD, PUT, DELETE, OPTIONS and TRACE are idempotent: repeating the request has the same intended effect as sending it once. POST is neither, which is why blindly retrying a failed POST can create duplicates. PATCH is defined in a separate specification.

Example

Creating and then reading an order. The status codes and the Location header carry meaning, not just the body.

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>

{"sku": "BOOK-42", "quantity": 1}

HTTP/1.1 201 Created
Location: /orders/981
Content-Type: application/json

{"id": 981, "sku": "BOOK-42", "quantity": 1, "status": "pending"}

GET /orders/981 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 981, "sku": "BOOK-42", "quantity": 1, "status": "pending"}

201 Created plus a Location header tells the client where the new resource lives. Sending the GET twice changes nothing on the server, so caches and retries are safe; sending the POST twice would create a second order unless the API adds an idempotency key.

Common confusion

Is every JSON-over-HTTP API a REST API?

Strictly, no. Fielding's definition includes hypermedia as the engine of application state: responses link to the actions available next. Most public APIs use resource URLs and HTTP methods but skip hypermedia, so they are more precisely called HTTP APIs or "RESTful". The label is used loosely in practice, and for most integrations the difference does not matter.

What is the difference between REST and GraphQL?

A REST API exposes many resource URLs, and the server decides what each response contains. GraphQL usually exposes a single endpoint where the client sends a query naming exactly the fields it wants. REST maps directly onto HTTP caching because each GET has its own URL; with GraphQL, caching typically moves into the client library or the application layer.