REST (Representational State Transfer) is an architectural style for building networked applications, described by Roy Fielding in his 2000 doctoral dissertation. A REST API uses HTTP as its communication protocol and organizes data around resources — things like users, products, or orders — each identified by a URL. REST is not a standard or a protocol; it is a set of constraints that, when followed, produce APIs that are scalable, stateless, and easy to consume.
Resources and URLs
In a REST API, every piece of data is a resource, and every resource has a unique URL. /users identifies the collection of all users. /users/42 identifies the user with ID 42. /users/42/orders identifies the orders belonging to that user. URLs should be nouns, not verbs — the action is expressed by the HTTP method, not the URL. /users/42/delete is not RESTful; DELETE /users/42 is.
HTTP Methods
- GET: retrieve a resource or collection. Safe and idempotent — should never modify data.
- POST: create a new resource. The response typically includes the new resource with its assigned ID.
- PUT: replace a resource entirely. Idempotent — sending the same request twice has the same effect as once.
- PATCH: partially update a resource. Send only the fields you want to change.
- DELETE: remove a resource. Idempotent — deleting something that does not exist should return 404 or 204, not an error.
Status Codes
HTTP status codes communicate the outcome of a request. The 2xx range indicates success: 200 OK (generic success), 201 Created (new resource created), 204 No Content (success with no body, common for DELETE). The 4xx range indicates client errors: 400 Bad Request (malformed input), 401 Unauthorized (authentication required), 403 Forbidden (authenticated but not allowed), 404 Not Found, 422 Unprocessable Entity (validation failure). The 5xx range indicates server errors: 500 Internal Server Error, 503 Service Unavailable.
Statelessness
A core REST constraint is that each request must contain all the information needed to process it — the server does not store session state between requests. Authentication credentials or tokens must be sent with every request. This makes REST APIs horizontally scalable: any server can handle any request without needing access to session storage. Statelessness also makes APIs easier to test and debug, since each request is self-contained.
REST vs. GraphQL vs. gRPC
GraphQL lets clients specify exactly which fields they need, reducing over-fetching and under-fetching. It is a good fit for complex, relationship-heavy data graphs and clients with varying data needs (mobile vs. web). gRPC uses Protocol Buffers for efficient binary serialization and is suited for high-performance internal service communication. REST remains the right default for public APIs, browser-consumed APIs, and any situation where HTTP's caching, tooling, and ubiquitous support are valuable.