Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 1 · Lesson 2 · 4 min read

What Is a REST API? Resources and Statelessness

On this page
  1. What is REST? Where it comes from
  2. Resources and representations
  3. HTTP methods: GET, POST, PUT, PATCH and DELETE
  4. What stateless means and why it helps scaling
  5. The other REST constraints, briefly
  6. REST vs RPC vs GraphQL
  7. Check yourself

What is REST? Where it comes from

REST (Representational State Transfer) comes from Roy Fielding's 2000 dissertation, describing why the web scaled so well. Most "REST APIs" today follow its main ideas loosely, and that's fine. The ideas that matter in practice are resources, a uniform interface, and statelessness.

Resources and representations

A resource is anything worth naming: an order, a customer, a collection of invoices. Each has a URL:

Code
/orders            the collection of orders
/orders/482        one order
/orders/482/items  the items in that order

Clients never touch the resource directly; they exchange representations of it, usually JSON. A photo of a building isn't the building, and a floor plan isn't either, but both describe it. In the same way, one order could be represented as JSON for an app or as a PDF for a printer (Day 5).

HTTP methods: GET, POST, PUT, PATCH and DELETE

Instead of inventing operations (getOrder, createOrder, cancelOrderNow), REST uses HTTP's methods on resources:

MethodMeaningExample
GETReadGET /orders/482
POSTCreate in a collection, or trigger a processPOST /orders
PUTReplace a resource completelyPUT /orders/482/shipping-address
PATCHChange part of a resourcePATCH /orders/482
DELETERemoveDELETE /orders/482

PUT and PATCH are the pair people mix up. PUT means "here is the whole new version", so fields you leave out are gone. PATCH means "change only these fields". Against a small Express API holding {"id":1,"name":"Ana","email":"ana@example.com","phone":"555-0100"}:

Code
PATCH /users/1 {"name":"Ana B"}  -> {"id":1,"name":"Ana B","email":"ana@example.com","phone":"555-0100"}
PUT   /users/1 {"name":"Ana C"}  -> {"id":1,"name":"Ana C"}

The PUT quietly removed the email and phone, because the client didn't send them. That's correct PUT behavior, and a common source of lost data when a client meant PATCH.

Because every API uses the same verbs with the same meanings, generic tools work everywhere: caches know GETs can be cached, proxies know GETs can be retried, and developers know what to expect (Days 4 and 10).

Clients exchange representations of resources using standard methods; each request carries its own authentication, so any server can handle it.
Clients exchange representations of resources using standard methods; each request carries its own authentication, so any server can handle it.

What stateless means and why it helps scaling

Each request must contain everything the server needs to process it. The server keeps no memory of the client between requests: no "current page" or "logged-in user" held in server memory.

Picture a busy coffee shop. If each order slip says the full order and the customer's name, any barista can make it. If the barista has to remember what you said earlier, only that one barista can serve you, and when they go on break your order is lost. Stateless requests are the complete slips.

HTTP
GET /orders/482
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

GET /orders/482/items
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Both requests carry their own credentials. They can land on different servers behind a load balancer, and both work. That's the practical payoff:

  • Easy scaling: add servers without sticky sessions or shared memory.
  • Resilience: a server can die between requests without losing anyone's session.
  • Simpler caching and retries, since each request stands alone.

Stateless doesn't mean the system has no state. Orders live in a database. It means session state lives with the client (tokens, cursors) or in shared storage, not in one server's memory.

The other REST constraints, briefly

  • Client-server: clients and servers evolve independently.
  • Cacheable: responses say whether they can be cached (Day 5).
  • Layered system: clients can't tell whether they're talking to the server or a proxy, CDN or gateway in between (Day 21).
  • Hypermedia (HATEOAS): responses link to related actions; the least adopted constraint (Day 9).

REST vs RPC vs GraphQL

RPC-style APIs (gRPC, JSON-RPC) model operations rather than resources and suit internal service-to-service calls. GraphQL (Days 14 to 20) lets clients ask for exactly the data they need. REST remains the default for public HTTP APIs because it builds on what HTTP and the web already provide.

Check yourself

Each request carries everything needed to process it, such as credentials and parameters; the server keeps no per-client session in memory between requests.

Any server can handle any request, so you can add or remove servers without sticky sessions or shared session memory.

Clients, caches and proxies already understand their meaning, safety and retry behavior, so the API works predictably with existing tools.

No. PUT replaces the whole resource, so omitted fields are removed. The client should send the full resource with PUT, or use PATCH to change one field.

The resource is the concept, such as order 482. A representation is one serialized form of it, like JSON or CSV, which the client can choose with the Accept header.