What Is a REST API? A Clear, Accurate Guide

A REST API is a way for two programs to talk over HTTP using a small, predictable set of rules. REST stands for Representational State Transfer, an architectural style described by Roy Fielding in his 2000 doctoral dissertation, and it has become the default approach for building web APIs.

This guide explains what REST actually is, how a request and response flow works, the constraints that make an API "RESTful," and the mistakes that trip people up. It assumes you know what an API is in general terms.

REST Is a Style, Not a Protocol

The most common misconception is that REST is a specific technology you install. It is not. REST is a set of architectural constraints that describe how clients and servers should interact. HTTP is the protocol; REST is a discipline for using HTTP well.

In Fielding's formulation, an architecture is RESTful when it satisfies several constraints: a clear client-server separation, statelessness, cacheability, a uniform interface, and a layered system. Code-on-demand (sending executable code to the client) is the one optional constraint. The uniform interface is itself the strictest part: in Fielding's definition it includes hypermedia controls in responses, so a client can discover what to do next from links the server returns. Most APIs called "REST" today skip that step and satisfy only some of the constraints, which is why the looser term "RESTful" is common.

Resources, URLs, and Representations

REST organizes an API around resources — the nouns your system manages, such as users, orders, or articles. Each resource is identified by a URL (more precisely a URI). A client never manipulates the resource directly; it exchanges a representation of that resource, typically as JSON.

Two ideas matter here. First, a resource and its representation are distinct: the same order might be sent as JSON to one client and XML to another. Second, the URL identifies the thing, not the action. Good REST design favors:

• /users — the collection of users
• /users/42 — a single user
• /users/42/orders — that user's orders

A common anti-pattern is putting verbs in the path, such as /getUser or /createOrder. In REST the verb comes from the HTTP method, not the URL.

HTTP Methods Carry the Intent

REST maps actions onto standard HTTP methods. The four you will use most are GET, POST, PUT, and DELETE, often summarized as CRUD (create, read, update, delete).

Safe means the method should not change server state — a GET must never delete data. Idempotent means making the same call repeatedly has the same effect as making it once. GET, PUT, and DELETE are idempotent; sending the same DELETE twice still leaves the resource gone. POST is not, which is why two identical POSTs can create two records. Respecting these properties is what lets clients, proxies, and caches retry requests safely.

What a Request and Response Look Like

A REST call is an ordinary HTTP message. Here is a request that creates a user, and the response the server might return.

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

{
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /users/42

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}

The pieces are: a method and path, headers (here declaring the body format and an auth token), and an optional body. The response mirrors that shape with a status code, headers, and a body. The Location header points to the newly created resource. You can experiment with requests like this using a REST client, or turn a saved curl command into source with a cURL to code converter, and a JSON formatter helps when responses arrive minified.

Status Codes Communicate the Outcome

REST leans heavily on HTTP status codes to tell the client what happened, instead of burying an error flag inside a "200 OK" body. The ranges are consistent:

• 2xx — success (200 OK, 201 Created, 204 No Content)
• 3xx — redirection (301 Moved Permanently, 304 Not Modified)
• 4xx — client error (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests)
• 5xx — server error (500 Internal Server Error, 503 Service Unavailable)

The distinction between 4xx and 5xx matters: a 4xx says the client must change something, while a 5xx says the server failed and the same request might succeed later. Returning the right code is part of a usable API. A status code reference and the guide to HTTP status codes cover the full list.

Statelessness, Auth, and Rate Limits

The statelessness constraint says each request must carry everything the server needs to process it; the server does not remember previous requests in session memory. This is why authentication travels in every request, usually as a bearer token in the Authorization header rather than a server-side session. Token formats and the trade-offs between them are covered in OAuth2 vs JWT.

Statelessness is what makes REST APIs scale horizontally: any server instance can handle any request, so you can add machines behind a load balancer freely. It also means servers protect themselves with rate limiting, returning 429 Too Many Requests when a client sends too many calls — see rate limit strategies for APIs.

Common Pitfalls and How REST Compares

A few mistakes show up repeatedly:

1. Verbs in URLs. /deleteUser/42 should be DELETE /users/42.
2. Always returning 200. Signaling failure only in the body breaks tooling that relies on status codes.
3. Ignoring idempotency. Using POST where PUT belongs makes safe retries impossible.
4. Unversioned APIs. Without a version (such as /v1/), a breaking change silently breaks every client.
5. Forgetting CORS. Browser-based clients need correct cross-origin headers; see what CORS is.

REST is not the only option. GraphQL lets clients request exactly the fields they need from a single endpoint, which can reduce over-fetching at the cost of more complex caching. Webhooks invert the flow so the server notifies the client when something happens, instead of the client polling. REST remains the most widely used style because it is simple, cache-friendly, and built directly on the HTTP that every browser, proxy, and server already speaks.

Frequently Asked Questions