What is a REST API?

REST (Representational State Transfer) is an architectural style for designing networked APIs. It isn't a protocol or a library — it's a set of conventions, layered on top of HTTP, for how clients and servers talk about resources. When people say "build a REST API," they mean: model your data as resources with URLs, manipulate them with HTTP methods, and exchange representations (usually JSON). Done well, REST gives you an API that's predictable, cacheable, and easy for any client to consume.

Resources, not actions

The core mental shift: a REST API exposes nouns (resources), and you act on them with HTTP's verbs. The URL identifies what; the method says what to do with it.

RPC-style (avoid)	RESTful (prefer)
`GET /getUsers`	`GET /users`
`POST /createUser`	`POST /users`
`POST /deleteUser?id=5`	`DELETE /users/5`
`POST /updateUserEmail`	`PATCH /users/5`

The verb lives in the HTTP method, never in the URL

A telltale sign of a non-RESTful API is verbs in the path: `/createUser`, `/getOrders`. In REST the path names the resource (`/users`, `/orders`) and the **method** (`GET`/`POST`/`PUT`/`PATCH`/`DELETE`) carries the action. This keeps a small, consistent vocabulary instead of an ever-growing list of bespoke endpoints.

The method ↔ CRUD mapping

Method	CRUD	On `/users`	On `/users/5`
`GET`	Read	List all users	Fetch user 5
`POST`	Create	Create a user	—
`PUT`	Replace	—	Replace user 5 wholesale
`PATCH`	Update	—	Partially update user 5
`DELETE`	Delete	—	Delete user 5

A representation is just data — usually JSON

JSON

// GET /users/5  →  a JSON representation of the resource
{
  "id": 5,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "createdAt": "2026-01-12T09:30:00Z"
}

The resource and its representation are distinct

The *resource* is the conceptual thing ("user 5"); the *representation* is a concrete serialization the server sends — typically JSON, but it could be XML, CSV, or HTML. The client and server negotiate format via the `Accept` and `Content-Type` headers. Modern APIs default to JSON, but the separation is why REST is format-agnostic.

Statelessness — the defining constraint

Each request carries everything the server needs to handle it — credentials, parameters, body. The server keeps no client session state between requests. This is what lets you run many identical server instances behind a load balancer: any one can handle any request.

Stateless ≠ no state — it means no *client session* on the server

Statelessness doesn't mean the server stores nothing — your database is full of state. It means the server doesn't remember *this client's* conversation between requests. Request N can't rely on the server "remembering" request N−1; the client re-sends its auth token (and any needed context) each time. Smuggling per-client state into server memory breaks horizontal scaling — the next request may hit a different instance. More in [REST principles](/nodejs/rest-principles).

What makes an API "RESTful"

Resource-based URLs — /articles/42/comments, not /getArticleComments.
Proper HTTP methods — the verb is the method; respect their semantics.
Meaningful status codes — 200, 201, 404, 422… not always 200 { "ok": false }.
Stateless requests — each one self-contained and independently routable.
Representations — exchange data (JSON), decoupled from internal storage.

Why REST won

Uses HTTP as-is — works with every browser, proxy, CDN, and HTTP client unchanged.
Cacheable — GETs can be cached by the same infrastructure that caches web pages.
Uniform & predictable — once you know the conventions, any REST API feels familiar.
Loose coupling — clients and servers evolve independently behind the contract.

REST is a style, not a strict standard — pragmatism wins

There's no REST compiler that rejects a "wrong" API. Real-world APIs (Stripe, GitHub) follow REST conventions closely but pragmatically bend them where it serves clients. The goal is a consistent, intuitive contract — not religious purity. Alternatives like GraphQL and gRPC exist for cases REST fits poorly, but REST remains the default for web APIs.

The formal constraints behind the style, and what each buys you: [REST Principles & Constraints](/nodejs/rest-principles).