{"canonical_url":"https://engineer.company/glossary/rest/","content_markdown":"# REST\n\n## What it is\n\nREST, short for Representational State Transfer, is the architectural style Roy\nFielding set out in chapter 5 of his dissertation in 2000. It is not a protocol\nand not a standard. It is a set of constraints on how clients, servers and the\nintermediaries between them may interact, and Fielding states what each\nconstraint buys and, for most of them, what it costs. RESTful is the adjective:\nstrictly, it describes a system that keeps all of the constraints. In everyday\nuse both words stretch much further, to almost any HTTP API that exchanges JSON,\nwhether or not it keeps the constraints below.\n\nThe central idea is the resource. In Fielding's words, “Any information that can\nbe named can be a resource”: a document, an image, a collection of other\nresources, a person, even the current weather in one city. What crosses the\nnetwork is never the resource itself but a representation, a sequence of bytes\nplus metadata that describes those bytes, such as an HTML document or a JPEG\nimage, and a client acts on a resource by sending or receiving a representation\nof its current or intended state.\n\nFielding builds the style up from an empty set of constraints, adding one at a\ntime. Client-server separates the user interface from data storage, so the two\ncan evolve independently. Stateless means that every request carries everything\nneeded to understand it and leans on no context stored on the server, so session\nstate lives entirely with the client. Cache requires each response to be\nlabelled, explicitly or implicitly, as cacheable or not, so that a client can\nreuse a cacheable one for a later, equivalent request. Uniform interface,\ndescribed below, gives every component the same general interface. Layered\nsystem means each component sees only the layer it talks to directly, which\nleaves room for proxies, gateways and firewalls in between without changing the\ninterfaces on either side. Code on demand lets a server extend a client by\nsending it scripts to run, and Fielding makes it the one optional constraint\nbecause it reduces visibility.\n\nHe calls the uniform interface the central feature that sets REST apart from\nother network-based styles, and splits it into four constraints: resources are\nidentified, on the web by URLs; resources are manipulated through\nrepresentations; messages are self-descriptive, so their meaning is visible to\nevery intermediary; and hypermedia is the engine of application state, which\nmeans the client chooses its next transition from the representations it has\nreceived, the way a person follows links in a browser.\n\n## Why it matters\n\nEach constraint pays for something specific. Statelessness lets a monitoring\nsystem understand a request without looking beyond it, makes it easier to\nrecover from partial failures, and lets a server free resources as soon as it\nhas answered. A cache can remove some interactions altogether. Layers let\nintermediaries spread load across networks and machines, and let one cache at\nthe edge of an organisation serve everyone inside it. And because the uniform\ninterface decouples implementations from the services they provide, a client and\na server can each change without the other having to change in step.\n\nFielding is just as plain about the costs. Statelessness repeats data in every\nrequest that a shared context on the server would have saved. A cache can hand\nout stale data. Every layer adds overhead and latency. The uniform interface\ndegrades efficiency, because information travels in a standardised form rather\nthan one shaped to the needs of a particular application. Fielding designed it\nfor large-grain hypermedia data transfer, the common case on the web, and says\nplainly that it is not optimal for other kinds of interaction. That is the\nground the alternatives stand on. A GraphQL server takes every request at a\nsingle endpoint, identifies its entities by something other than URLs and lets\nthe client choose exactly which fields come back, while gRPC calls methods\ndeclared in a service definition. Each gives up part of the uniform interface to\nsuit a different kind of traffic.\n\nFor an HTTP API, much of the uniform interface comes ready-made. HTTP already\ndefines methods with agreed meanings, status codes, and header fields for\ncaching and for conditional requests. Because that meaning is shared, a proxy or\ncache on the way can act on a message without knowing anything about the\nparticular API, and an API that uses these parts as defined gets that machinery\nfor free. An API that hands its clients URL templates to fill in, rather than\nlinks to follow, gives up the hypermedia constraint, and its clients are tied to\nthe server's URL layout: when that layout changes, they break, which is the\ncoupling the uniform interface exists to remove.\n\n## What it looks like in practice\n\nThe exchange below creates an order and is answered with the address of the new\nresource in `Location` and an entity tag in `ETag`. RFC 9110 uses an `ETag` in a\n201 response as its own example: the tag can serve as a validator in later\nconditional requests, so that two clients cannot silently overwrite each other's\nchanges.\n\n```http\nPOST /orders HTTP/1.1\nHost: api.example.com\nContent-Type: application/json\n\n{\"item\": \"notebook\", \"quantity\": 2}\n\nHTTP/1.1 201 Created\nLocation: /orders/7421\nETag: \"v1\"\nContent-Type: application/json\n\n{\"id\": 7421, \"item\": \"notebook\", \"quantity\": 2, \"status\": \"open\"}\n```\n\nEvery method carries a meaning that any intermediary may rely on. RFC 9110\ndefines GET, HEAD, OPTIONS and TRACE as safe: the client neither asks for nor\nexpects any change of state on the server. PUT and DELETE, together with the\nsafe methods, are idempotent, so several identical requests have the same\nintended effect as one. POST is neither, and RFC 5789 says the same of PATCH.\nThose two properties are what let a crawler follow links without doing harm, let\na cache fetch ahead, and let a client repeat a PUT whose connection dropped\nbefore the answer arrived.\n\nA REST API can be driven with nothing more than a generic HTTP client, and this\nsite shows both what that saves and what it costs. When a second server was\nprovisioned from code,\n[the firewalls at both cloud providers were configured straight through their REST APIs with a generic HTTP task](/portfolio/provisioned-a-second-server-from-code/)\ninstead of a vendor collection. That removes a dependency and its version drift,\nand the price is writing the shape of every request by hand. The same page names\na second cost: the generic HTTP task declares no check-mode support, so a dry\nrun of the play that creates the machine skips every task in it.\n\n## Where it goes wrong\n\n**A GET changes something.** An address such as `/orders/7421/cancel` that\ncancels an order when it is fetched breaks the promise that GET is safe. RFC\n9110 explains why that promise exists: so that crawlers and caches that fetch\nahead can work without fear of causing harm. The first crawler or prefetching\ncache to come across the link cancels the order. Put the action in the method\ninstead, as a POST to the order or a PATCH of its status.\n\n**Every answer is 200 OK.** Some APIs return 200 for everything and put the real\noutcome, error or not, in the body. The messages stop being self-descriptive:\ncaches, proxies, monitoring and client libraries all read the status code, and\nall of them see success. RFC 9457 defines a standard body for errors,\n`application/problem+json`, with members such as `type`, `title`, `status` and\n`detail`. Its `status` member is only advisory: the server must send the same\nstatus code in the HTTP response itself, so that generic HTTP software which\nknows nothing of the format behaves correctly.\n\n**A retried POST creates two orders.** When a connection drops after the server\nhas processed a POST but before the client has read the answer, the client\ncannot tell whether the order exists. RFC 9110 says a client should not retry a\nnon-idempotent request automatically unless it knows that the request is\nidempotent after all, or can tell that the first attempt was never applied, and\nthat a proxy must not do so at all. It also notes that some clients take the\nriskier path and retry a POST anyway when the connection closes before any of\nthe answer arrives, particularly on an idle persistent connection. One way out\nis to let the client choose the identifier and PUT the order to it, because PUT\nis idempotent: the first request creates the order with 201, and a repeat only\nreplaces it with the same state.\n\n**Two clients overwrite each other.** Both read the order, both change a\ndifferent field, and both PUT the whole thing back: the second write silently\nundoes the first. RFC 9110 calls this the lost update problem. The fix is the\nentity tag each client got when it read the order, sent back in `If-Match`. The\nserver then applies the change only if the resource is still in the state that\nclient last saw; if it is not, the server must not apply it and can say so with\n412 Precondition Failed. The client then reads the order again, reapplies its\nchange and tries once more.\n\n```http\nPUT /orders/7421 HTTP/1.1\nHost: api.example.com\nIf-Match: \"v1\"\nContent-Type: application/json\n\n{\"item\": \"notebook\", \"quantity\": 3, \"status\": \"open\"}\n\nHTTP/1.1 412 Precondition Failed\n```\n\n**The server remembers the conversation.** A server that keeps per-client state\nbetween requests, such as the current page of a listing or a half-finished form\nheld in memory, has dropped the stateless constraint. A request no longer makes\nsense on its own, the load balancer has to send each client back to the same\nmachine, and a restart throws the state away. Fielding's reasons for\nstatelessness are exactly the ones lost: visibility, easier recovery from\npartial failure, and a server that can free resources once it has answered. Put\nthe state in the request, as a page token in the URL, or turn the half-finished\nthing into a resource of its own, such as a draft order, that any server can\nread.\n\n## Further reading\n\n- [Fielding, chapter 5: Representational State Transfer (REST)](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)\n  — the definition: each constraint, the properties it induces and what it\n  trades away for them.\n- [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110) — methods,\n  safety and idempotency, status codes, and conditional requests with `ETag` and\n  `If-Match`.\n- [RFC 5789: PATCH Method for HTTP](https://www.rfc-editor.org/rfc/rfc5789) —\n  partial modification of a resource, and why PATCH is neither safe nor\n  idempotent.\n- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457)\n  — a standard JSON body for error responses that keeps the status code\n  meaningful.\n\n\u003chttps://engineer.company/glossary/rest/\u003e\n","date_modified":"2026-10-30T02:51:31Z","description":"The constraints Roy Fielding set out for the web, what they buy and what they cost, and five ways an HTTP API that calls itself REST goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/rest/index.gmi","gopher":"https://engineer.company/glossary/rest/gophermap","html":"https://engineer.company/glossary/rest/","json":"https://engineer.company/glossary/rest/index.json","markdown":"https://engineer.company/glossary/rest/index.md","pdf":"https://engineer.company/glossary/rest/index.pdf"},"kind":"page","language":"en","title":"What is REST?","url":"https://engineer.company/glossary/rest/","version":1}