REST

The architectural style behind most HTTP APIs: resources with URLs, a few standard methods, status codes and cacheable responses, named by Roy Fielding in 2000.

What it is: Web APIs
Type: Open source
Made by: Architectural style (Roy Fielding, 2000); HTTP itself is an IETF standard
Facts checked: 6 October 2026

What it is

REST is a set of design constraints, not a protocol or a product. In practice a REST API is a set of URLs, each naming a resource (/orders, /orders/4812, /orders/4812/items), and clients act on them with HTTP methods whose meaning RFC 9110 fixes for everyone: GET and HEAD are safe, meaning they only read; PUT and DELETE are idempotent, so sending one twice has the same effect as sending it once; POST is neither. The server answers with a representation of the resource, usually JSON, and a status code: 2xx for success, 3xx for look elsewhere, 4xx for the client’s mistake, 5xx for the server’s. It keeps no session between requests: each one carries its own credentials and context, typically a token in the Authorization header, so any instance behind a load balancer can answer. Responses say how they may be cached. Cache-Control: max-age=60 lets browsers, CDNs and proxies reuse a GET response for a minute; an ETag lets a client revalidate with If-None-Match and get an empty 304 Not Modified when nothing changed, or update with If-Match and get 412 Precondition Failed if someone else changed the resource first. Many APIs return errors as JSON in the application/problem+json format of RFC 9457.

Fielding’s definition asks for more than most APIs do. Its uniform interface includes hypermedia as the engine of application state (HATEOAS): responses carry links that tell the client what it can do next, so clients follow links instead of building URLs from documentation. Few public APIs work that way, and in 2008 Fielding wrote that an HTTP API not driven by hypertext “cannot be RESTful”. In everyday use, “REST API” means resource URLs, HTTP methods and JSON, with the rest (URL layout, pagination, versioning, error format) chosen by each API. Teams pin those choices down in an OpenAPI document, a YAML or JSON file listing paths, parameters, request and response schemas and auth schemes; version 3.2.1, published in September 2026, is current. Tools generate documentation, client SDKs and request validation from it, and Amazon API Gateway, Google’s API Gateway and Azure API Management can import it. There is nothing to buy: REST is a style, HTTP is an IETF standard, and the OpenAPI Specification is Apache 2.0-licensed.

Why teams pick it

Any HTTP client can call it: browsers, curl, every language’s standard library, with no code generation or translating proxy
HTTP infrastructure understands it: browsers and CDNs cache GET responses, load balancers and gateways route by method and path, and logs show readable URLs and status codes
Shared rules from the standard: safe and idempotent methods tell clients what they may retry, and status codes and conditional requests (ETag, If-Match) mean the same thing on every API
Statelessness makes scaling out simple: any server instance can answer any request
Mature tooling around OpenAPI: generated docs and SDKs, mock servers, request validation and gateway imports

Watch out for

Over- and under-fetching: each endpoint returns a fixed shape, so a client gets fields it doesn’t need or makes several round trips to fill one screen, the gap that led Facebook to build GraphQL
No single standard: REST is a style, so URL layout, pagination, filtering, error bodies and auth differ from API to API, and every client learns each one afresh. An OpenAPI document records those choices; it doesn’t make them for you
Versioning is up to you, and large API publishers disagree: Google puts a major version in the path (/v1/), Azure requires an api-version query parameter, and GitHub uses a dated X-GitHub-Api-Version header
POST isn’t idempotent, so retrying a timed-out create can make a duplicate. An IETF draft for a standard Idempotency-Key header expired in 2026 without becoming an RFC; APIs such as Stripe’s define their own
Hypermedia is rarely implemented, so clients hard-code URLs and break when they move; by Fielding’s own definition most “REST APIs” are HTTP-based RPC

Alternatives

What all web apis have in common →

GraphQLOpen sourceA query language and runtime for APIs: the server publishes a typed schema, and each client asks one endpoint for exactly the fields it needs.

How it fits with other technologies

What REST uses

What uses REST

Create an order, then change it only if nobody else has · http

# POST isn’t idempotent: the key lets the server spot a retried create
POST /v1/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJFUzI1NiJ9...
Content-Type: application/json
Idempotency-Key: 5f1c2a9e-4b7d-4c1e-9f63-0d2b8a7e1c44

{"customer_id": "c-77", "items": [{"sku": "MUG-01", "qty": 2}]}

HTTP/1.1 201 Created
Location: /v1/orders/4812
ETag: "1"
Content-Type: application/json

{"id": "4812", "status": "pending", "total_cents": 2400}

# If-Match: apply the change only to version "1" of the order
PATCH /v1/orders/4812 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJFUzI1NiJ9...
Content-Type: application/merge-patch+json
If-Match: "1"

{"status": "cancelled"}

# Someone else changed it in the meantime
HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

{"type": "https://api.example.com/problems/stale-order", "title": "The order changed since you read it", "status": 412}

What each HTTP method promises#

These properties come from the HTTP standard (RFC 9110, and RFC 5789 for PATCH), so clients, proxies and caches can rely on them without reading your docs.

	Safe (read-only)	Idempotent (safe to repeat)	Response cacheable	Typical use
`GET`	Yes	Yes	Yes	Read a resource or a list
`HEAD`	Yes	Yes	Yes	Headers only: check existence, size or `ETag`
`POST`	No	No	Only with explicit freshness and a matching `Content-Location`	Create in a collection, or run an action
`PUT`	No	Yes	No	Create or replace at a known URL
`PATCH`	No	No (can be made so with `If-Match`)	No	Change part of a resource
`DELETE`	No	Yes	No	Remove a resource

A successful PUT, POST or DELETE that passes through a cache makes it invalidate what it stored for that URL (RFC 9111).

Three ways large APIs handle versions#

REST leaves versioning to each API. Three of the biggest publishers picked three different places for the version.

Google

in the path

Every Google API has a major version number as the first part of the URL path, such as v1, with no minor or patch numbers; an incompatible change means a new major version.

Microsoft Azure

query parameter

Every operation requires an api-version query parameter named by date, as in PUT https://service.azure.com/users/Jeff?api-version=2021-06-04; leaving it out returns 400.

GitHub

header

Clients send an X-GitHub-Api-Version header with a date such as 2026-03-10; requests without it get the 2022-11-28 version.

See it in a real stack

No architecture uses REST yet. Drop it into the playground and wire it up yourself.Open playground →

Where it came from1994–2022

In 1993 the web was described by informal notes and draft specifications that, after Mosaic arrived, were far behind what browsers and servers actually did. Roy Fielding, a graduate student at UC Irvine writing the libwww-perl library, joined the standards work, co-authored the HTTP/1.0 specification with Henrik Frystyk Nielsen and became the primary architect of HTTP/1.1. Between October 1994 and August 1995 he worked out a model to explain how the web should behave while those specs were written. He first called it the “HTTP object model”, but people kept mistaking it for the design of an HTTP server.

His 2000 dissertation renamed it Representational State Transfer and built it up as a series of constraints: client and server, stateless requests, cacheable responses, a uniform interface, layers of intermediaries and optional code sent to the client. Each one gave up something, such as efficiency, for a property the web needed at internet scale.

The name was soon used for web APIs that used HTTP directly instead of SOAP envelopes; Amazon S3 launched in 2006 with both. By 2008 Fielding was “frustrated by the number of people calling any HTTP-based interface a REST API”. Swagger, created in 2010, became the OpenAPI Specification in 2015, and in 2022 RFC 9110, which Fielding co-edited, restated HTTP’s semantics.

Why it’s built this way

A uniform interface instead of application-specific operations: Fielding called it the central feature that distinguishes REST: the same few methods on every resource keep the architecture simple and let intermediaries see what each request does. He accepted that this “degrades efficiency”, since data moves in a standard form rather than one fitted to each application.
Stateless requests: Each request must carry everything needed to understand it. That costs some repeated data per request but makes requests visible to monitors, failures easier to recover from, and servers quicker to free resources, so they scale.
Responses labelled cacheable or not: A cache can reuse a response for later equivalent requests and skip some interactions entirely, cutting latency. The trade-off Fielding named is that a cache can serve stale data.
Layers that can’t see past their neighbours: Proxies, gateways and shared caches can sit between client and server without either knowing. Layers add latency, but shared caches at organisation boundaries can more than make up for it.

Timeline

1994
Fielding starts the “HTTP object model” in October
1996
HTTP/1.0 published as RFC 1945 in May
1999
HTTP/1.1 published as RFC 2616 in June
2000
Fielding’s dissertation defines REST
2006
Amazon S3 launches with REST and SOAP interfaces
2015
The OpenAPI Initiative forms around Swagger
2022
RFC 9110 and RFC 9111 restate HTTP semantics and caching

Sources23 · facts checked 6 October 2026

Improve this page on GitHub