APIs & Authentication
What is a REST API?
An API that follows REST conventions, using HTTP methods on resource URLs to model create/read/update/delete operations.
REST (Representational State Transfer) is an architectural style described by Roy Fielding in 2000. The relevant principles for everyday work: resources have URLs (/users/42), HTTP methods describe the operation (GET to read, POST to create, PUT/PATCH to update, DELETE to remove), and the server returns a representation of the resource, usually JSON.
In practice, "REST API" today means "JSON over HTTP that uses verbs sensibly." Strict Fielding-style REST with HATEOAS hyperlinks is rare; most real APIs are JSON-RPC dressed up in REST clothes, and that's fine. The conventions are valuable; the dogma is not.
REST won the API war in the 2010s by being radically simpler than SOAP. GraphQL and gRPC have eaten chunks of its territory since, but for public APIs that need to be approachable from any language, REST is still the safe default.
In the wild
- →
GET /users, list users - →
POST /userswith JSON body, create a user - →
DELETE /users/42, remove user 42
How Brand.dev uses rest api
Endpoints in the Brand.dev API where this concept comes up directly.
FAQ
REST vs GraphQL?
REST is many endpoints, each returning a fixed shape. GraphQL is one endpoint, where the client specifies the shape it wants. REST is simpler to cache and operate; GraphQL is better when clients need very different slices of the same graph.
What status codes should a REST API use?
At minimum: 200 OK for reads, 201 Created for creates, 204 No Content for deletes, 400/422 for bad input, 401/403 for auth, 404 for missing resources, 429 for rate-limited, 500 for server bugs.
Is REST stateless?
Per the spec, yes, every request carries everything the server needs to understand it. In practice, sessions and auth tokens count as state in the client; REST just means the server doesn't hold per-client state in memory between requests.
Related terms
An Application Programming Interface, a contract that lets one program request actions or data from another in a stable, documented way.
A query language for APIs that lets the client specify exactly the fields it wants from a typed graph of data, returned in one round trip.
The application protocol the web is built on, a simple request/response format for asking a server for a resource.
JavaScript Object Notation, a lightweight text format for representing structured data, supported natively by every modern language.