What is REST API?

How it works

A REST API lets clients read and change resources, such as orders or users, at URLs by using standard HTTP methods and status codes. REST (Representational State Transfer) is an architectural style that Roy Fielding described in his doctoral dissertation. It is a set of constraints that no tool can certify, so teams check an API against the constraints and the common conventions built on them.

Fielding names six constraints: client-server, stateless, cacheable, a uniform interface, a layered system, and code on demand, which he calls optional. Stateless means each request carries all the information the server needs to understand it, so the server keeps no session state between calls. The uniform interface has four parts: resources are identified by URLs, clients change them through representations such as JSON, messages describe themselves, and responses link to related actions (hypermedia).

In practice, a path names a thing and the HTTP method names the action. GET /orders/42 returns an order. POST /orders creates one. PUT /orders/42 replaces it, PATCH changes part of it, and DELETE removes it. The status code reports the outcome. RFC 9110 defines GET, HEAD and OPTIONS as safe, meaning read-only, and PUT and DELETE as idempotent, meaning repeating the request has the same effect as sending it once. POST is neither, so clients should not retry it blindly. Idempotency explains why that matters for retries, and HTTP status codes lists which code fits which outcome.

An OpenAPI file describes a REST API as paths and operations, which makes the conventions checkable. When we scored a small example spec in APIForge, a path called /api/createOrder was flagged for using camelCase and a verb, two operations were flagged for documenting no error responses, and the whole spec was flagged for having no version in its paths. The score came to 78 out of 100. The REST API design best practices, naming conventions and error handling guides explain each rule.

Example

paths:
  /orders:
    get:
      summary: List orders
    post:
      summary: Create an order
  /orders/{id}:
    get:
      summary: Get one order
    put:
      summary: Replace an order
    delete:
      summary: Delete an order

Common mistakes

• Using POST for every operation, which gives up the caching of GET and the safe retries of PUT and DELETE.
• Putting verbs in resource paths, such as /getUser or /createOrder. The HTTP method already names the action.
• Returning 200 OK with an error in the body, which hides failures from clients, caches and monitoring tools.
• Keeping session state on the server between requests, which breaks the stateless constraint and makes scaling harder.
• Calling any JSON-over-HTTP API REST. An API that sends every call to one endpoint with an action name in the body is RPC-style.