REST API
Also known as: RESTful API
A common style of web API where each thing has its own URL and programs use plain HTTP methods to read, add, change or delete it.
Draft - this entry has not been reviewed yet.
Formal
An API that follows the REST style described by Roy Fielding in 2000 - each resource has its own URL, HTTP methods such as GET, POST, PUT and DELETE say what to do with it, and the server keeps no memory of the client between requests.
In plain English
Like a library where every book has a fixed shelf number, and there are only a handful of desk requests - borrow, return, add, remove - that work the same for every book.
In practice
A ferry company's booking app sends GET to the address for booking 42 to show its status, and DELETE to the same address when the passenger cancels the trip.
Why it matters
Its simple, shared rules let any team build a client without special tools; each address is also a door into the system, so every one needs its own access checks.
Technical deep dive
In chapter 5 of his 2000 dissertation Roy Fielding derives REST by adding constraints one at a time: client-server, stateless (each request carries everything needed to understand it), cacheable responses, a uniform interface, a layered system and optional code-on-demand. The uniform interface has four sub-constraints: identification of resources, manipulation of resources through representations, self-descriptive messages, and hypermedia as the engine of application state (HATEOAS), meaning clients discover next actions from links in responses rather than from out-of-band knowledge. Most APIs marketed as REST ignore hypermedia, which Fielding criticised publicly in 2008; the Richardson Maturity Model grades APIs from level 0 (one endpoint, RPC over HTTP) through resources and HTTP verbs to level 3 (hypermedia controls).
The conventional mapping uses HTTP semantics directly. GET retrieves and is safe and cacheable; POST to a collection creates a subordinate resource, answering 201 Created with a Location header, and is not idempotent; PUT replaces a resource and is idempotent; PATCH (RFC 5789) applies a partial change, expressed either as JSON Merge Patch (RFC 7396) or as a JSON Patch operation list (RFC 6902); DELETE removes. Lost updates are prevented with ETags and If-Match, answered with 412 Precondition Failed on conflict. Errors are increasingly returned as problem details (application/problem+json, RFC 9457, which obsoleted RFC 7807), and pagination uses cursors or Link headers (RFC 8288). Because POST is not idempotent, safe retries require an idempotency key agreed between client and server.
Contracts are described with the OpenAPI Specification, which grew out of Swagger 2.0 and was donated to the Linux Foundation's OpenAPI Initiative in 2015; version 3.1 aligned its schema dialect with JSON Schema 2020-12. The description drives documentation, client code generation, contract testing and request validation at gateways.
The resource-per-URL design makes object identifiers visible in every request, which is why Broken Object Level Authorization is API1 in the OWASP API Security Top 10 (2023): changing /bookings/42 to /bookings/43 must be refused by an ownership check on the server, and switching to UUIDs only makes guessing harder without fixing the flaw. PUT and PATCH endpoints that bind the request body straight onto a data model enable mass assignment of fields such as isAdmin (part of API3:2023), and method-override headers such as X-HTTP-Method-Override can bypass access rules written per HTTP method. REST contrasts with GraphQL, where one endpoint accepts client-shaped queries, and with gRPC, which exposes procedures rather than resources.
What to learn first
Everything this builds on, foundations first.
Relationships
Sources & further reading
Official documentation
- MDN Web Docs - Glossary, REST · Mozilla
Reference works
- Roy T. Fielding - Architectural Styles and the Design of Network-based Software Architectures (Chapter 5, REST) · University of California, Irvine
Where this data comes from
This entry was drafted by an AI from the sources above and has not yet been checked by a person. Treat it as a starting point, and check anything important against the sources.
See the review queueSuggest a correction on GitHubThis term as JSON
Check yourself
Loading…