Almost every app on your phone talks to a server through an API, and most of those APIs call themselves REST APIs. A REST API is not a product, a library, or a protocol you install. It is an architectural style: a set of constraints for how a client and a server should talk over HTTP, defined by Roy Fielding in his 2000 doctoral dissertation at the University of California, Irvine. Understanding those constraints explains why endpoints look the way they do, why the same five HTTP methods show up everywhere, and why a three digit number can tell you exactly what went wrong.
Key Takeaways
REST stands for Representational State Transfer, an architectural style defined by Roy Fielding in 2000, not a standard or a protocol.
Resources are nouns with stable URLs, like `/users/42`. HTTP methods are the verbs: GET reads, POST creates, PUT replaces, PATCH updates part of a resource, DELETE removes it.
A request should be stateless: it carries everything the server needs, so any server can answer it without remembering previous requests.
Status codes are grouped by class: 2xx means success, 3xx redirection, 4xx a client error, 5xx a server error.
Most APIs that call themselves REST are really resource oriented HTTP APIs. That is fine, and it is still the most widely understood way to build a public API.
What REST Actually Is
Fielding introduced REST to describe the architecture that already made the web scale. In his dissertation, REST is a set of six constraints, and an API that follows them is called RESTful. The constraints, as summarized by Wikipedia and the Art of Code backend API design guide, are:
Client-server. The user interface and the data storage are separate concerns, so each can evolve independently.
Stateless. Every request carries everything the server needs to understand it. The server stores no client session between requests.
Cacheable. Responses must say whether they can be cached, so clients and intermediaries can reuse them.
Uniform interface. Every resource is handled the same way, through a consistent set of operations.
Layered system. A client cannot tell whether it talks to the origin server, a proxy, or a cache in between.
Code on demand (optional). The server may send executable code, such as scripts, for the client to run.
The uniform interface itself has four parts: resources are identified by URLs, they are changed through representations (usually JSON today), messages are self descriptive (method, headers, and media type explain how to read them), and hypermedia drives application state, meaning responses contain links to what you can do next. That last part, often called HATEOAS, is the one almost nobody implements in practice. Fielding himself noted his frustration that people call any HTTP interface a REST API. The honest label for most real world APIs is resource oriented HTTP API, and this article uses REST in that everyday sense.
Resources Are Nouns, Methods Are Verbs
The core design rule is simple: model things as resources, give each one a stable URL, and use HTTP methods to act on them. A user is a resource. A list of users is a collection resource. A single order is a resource. The URL is the noun, the method is the verb.
GET /users returns the list of users. GET /users/42 returns user 42.
POST /users creates a new user in the collection, with the data in the request body.
PUT /users/42 replaces user 42 entirely with the body you send.
PATCH /users/42 changes only the fields you send, leaving the rest untouched.
DELETE /users/42 removes user 42.
Two properties of methods matter more than their names. A method is safe when it never changes state, so GET, HEAD, and OPTIONS are safe. A method is idempotent when sending it once or many times has the same effect, so PUT and DELETE are idempotent while POST is not. The Art of Code guide notes that RFC 9110 defines these terms, and that clients, proxies, and retry logic rely on them. That is why a failed request can be safely retried for PUT but must not be blindly retried for POST: retrying a payment POST without an idempotency key could charge twice, while retrying a PUT just rewrites the same data.
Good endpoint design follows from this. Use plural nouns for collections (`/users`, `/orders`), nest only one level deep (`/users/42/orders`), filter with query parameters (`/orders?status=shipped`), and never put a verb in the URL. `GET /users/42/cancel` breaks the model: a crawler or link previewer could call it, and it would change state on a safe method. The RESTful shape is `POST /users/42/cancellation` or a status update with PATCH, where the action is explicit and the method is not safe.
A Request, Step by Step
A REST request is plain HTTP, and seeing its parts removes the mystery. Take a request to read a user profile:
Method and URL: `GET https://api.example.com/users/42`
Headers: `Accept: application/json` says what format the client wants, and `Authorization: Bearer <token>` proves who the caller is.
Body: GET requests usually have no body. POST and PUT carry one, typically JSON.
The server answers with three parts of its own:
Status code: a three digit number, such as 200 for success or 404 for a missing resource.
Headers: `Content-Type: application/json` says what the body is, and cache headers say whether it can be stored.
Body: the representation of the resource, usually JSON, such as `{"id": 42, "name": "Zahra", "email": "zahra@example.com"}`.
Because the request is stateless, the server needs the token on every call. That sounds wasteful, but it is what makes APIs scale: any server behind a load balancer can answer any request, no server has to remember your session, and a failed server can be replaced without losing anyone's state. The trade is that the client must resend its credentials and context each time, which is why tokens, not server side sessions, are the standard for public APIs.
Status Codes: The Server's Short Answer
Status codes are grouped into five classes, and learning the classes is more useful than memorizing every code. The common codes, as listed in standard references, are:
2xx, success: 200 OK (the request succeeded), 201 Created (a POST made a new resource), 204 No Content (success, nothing to return, common for DELETE).
3xx, redirection: 301 Moved Permanently, 302 Found (temporary redirect), 304 Not Modified (your cached copy is still good).
4xx, client error: 400 Bad Request (malformed or invalid input), 401 Unauthorized (authentication missing or failed), 403 Forbidden (authenticated but not allowed), 404 Not Found (no such resource), 409 Conflict (a duplicate or version clash), 429 Too Many Requests (rate limited).
5xx, server error: 500 Internal Server Error (an unexpected failure), 502 Bad Gateway (an upstream service returned a bad response), 503 Service Unavailable (overloaded or down for maintenance).
The class tells you who should act. A 4xx error means fix the request: check the URL, the token, or the body. A 5xx error means the problem is on the server's side, and retrying later may work. Good APIs also return a useful error body with a 4xx code, not just the number: which field failed, why it failed, and what a correct value looks like. A bare 400 with no explanation forces every developer to guess, and guessing is how bugs ship.
Authentication, Versioning, and Pagination
Three practical questions come up in almost every real API, and REST gives them conventional answers rather than strict rules.
Authentication usually means a token sent in the `Authorization` header. The common patterns are API keys for server to server calls and OAuth 2.0 bearer tokens for user facing apps, where a short lived access token is refreshed with a longer lived refresh token. The server checks the token on every request, which keeps the stateless constraint intact.
Pagination answers a simple problem: a collection with a million items cannot be returned in one response. APIs typically return a page at a time, with query parameters like `?page=2&limit=50` or cursor parameters like `?after=<id>`, plus metadata for the total count or a link to the next page. Cursor pagination is preferred for large or changing lists, because page numbers shift when items are added or removed.
Versioning answers a harder problem: how to change an API without breaking every client. The common approaches are a version in the URL (`/v1/users`, `/v2/users`) or a version in a header. URL versioning is the most visible and the easiest to debug, and it is what most public APIs choose. Whatever the scheme, the rule is the same: never silently change a field's meaning. Add new fields freely, deprecate old ones with notice, and only remove them in a new major version.
Where REST Fits, and Where It Does Not
REST is the default for public APIs for good reasons: it uses the web's own machinery, it is easy to cache, it is easy to debug with ordinary HTTP tools, and almost every language has a client for it. It also has honest limits. A client that needs exactly five fields from three resources must make several requests or accept overfetching, which is the problem GraphQL was designed to solve. A client that needs live updates must poll or add a separate channel such as WebSockets or server sent events, because HTTP requests are initiated by the client. And strict HATEOAS, where clients discover every action from links in responses, is rarely worth the complexity when the client and server are built by the same team.
That is why the landscape today is mixed rather than dogmatic. Public data APIs stay RESTful because they are simple and cacheable. Internal services sometimes use gRPC for speed. Product front ends sometimes use GraphQL to shape responses precisely. Knowing REST still pays off in all of those cases, because the concepts, resources, methods, status codes, statelessness, and caching, show up everywhere, even when the protocol changes. If you want the container side of the same story, the earlier explainer Docker Explained: What Containers Are and Why Developers Love Them covers how those API servers actually run in production.
Frequently Asked Questions
Is a REST API the same as an HTTP API?
Not exactly. Every REST API uses HTTP, but not every HTTP API is RESTful. REST adds constraints: resources with stable URLs, a uniform interface, stateless requests, and cacheable responses. Most APIs labeled REST are resource oriented HTTP APIs that follow most of those constraints but skip hypermedia.
Why JSON and not XML?
JSON won because it maps directly to the data structures of modern languages, it is compact, and it is easy to read. XML is still used in some enterprise and legacy systems, but new public APIs almost always choose JSON.
What is the difference between PUT and PATCH?
PUT replaces the whole resource with the body you send, so missing fields are treated as removed. PATCH changes only the fields you send. Use PUT when the client has the complete new state, and PATCH when it only wants to change one or two fields.
What should a POST return?
A successful creation should return 201 Created, ideally with a `Location` header pointing to the new resource's URL and the created resource in the body. Returning 200 with the resource is also common, but 201 is more precise.
How do I handle errors in a client?
Check the status class first. On 4xx, show or log the error body and fix the request; do not retry blindly. On 5xx or a network failure, retry with a delay, but only for safe or idempotent methods unless the API provides an idempotency key.
Do I need to learn REST to use an API?
You need the vocabulary: resources, methods, status codes, headers, and tokens. With those five ideas, you can read almost any API documentation and make your first successful call within minutes.
The Bottom Line
REST survived for more than two decades because it is less a technology than a discipline: name things as resources, use the verbs HTTP already gives you, answer with honest status codes, and keep every request self contained. Learn those habits and API documentation stops looking like a wall of endpoints and starts looking like a map. The next time you see `GET /users/42` return 404, you will know three things at once: what was asked for, what went wrong, and who should fix it.
Read this article in Indonesian: REST API Dijelaskan: Cara Kerja Gaya API Web yang Paling Umum.