REST Web Services: What a REST API Is and How It Works

Separating the two ideas has a practical payoff. A resource keeps its address while the formats offered for it grow or change. A client written against the JSON representation of order 42 keeps working when an XML representation appears next to it, because the address and the meaning of the order did not move.

Both rows describe the same order. Which format fits a given job is a separate question, taken up in XML vs JSON.

Addresses follow from this idea. Because the HTTP method already carries the action, resource URIs usually name things, such as /orders/42, rather than actions, such as /getOrder. That is common design advice and not a rule of the dissertation. Where a domain really contains a process, such as a payment run, modelling the process itself as a resource is a reasonable way out.

What does a REST API example look like?

A short order service shows the pieces working together. The host name is a placeholder.

1. The client creates an order by sending a POST to the collection, /orders, with a representation of the new order in the body.
2. The server creates it and answers 201 Created. RFC 9110 says a server that created a resource by POST should send 201 with a Location header, and here Location points to /orders/42.
3. The client reads the order with GET /orders/42. The answer is 200 OK with a representation in the body.
4. To change it, the client sends PUT to the same address with the complete new state. The server answers 200 or 204.
5. To remove it, the client sends DELETE. A 204 No Content response confirms success without a body.

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{"item": "notebook", "quantity": 2}

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

{"id": 42, "item": "notebook", "quantity": 2}

Steps four and five show why the choice of method matters. PUT names the address and supplies the whole new state, so sending it twice leaves the order as it was after the first call. DELETE behaves the same way: once the order is gone, a repeat has nothing further to remove. POST to the collection is different, because each call asks the server to make something new.

Every line has a job. The method and URI say what is addressed and what should happen, the media types say how to read the body, the status code reports the outcome, and Location gives the client an address it can use without guessing.

What is the difference between HTTP and a REST API?

RFC 9110 begins by calling HTTP “a stateless application-level protocol for distributed, collaborative, hypertext information systems”. A protocol fixes message formats, methods and status codes. REST fixes none of those. It is a set of constraints that a design can satisfy while using a protocol such as HTTP.

An HTTP API can break the style without breaking the protocol. A single endpoint that accepts every action as a POST with a command in the body is valid HTTP. It also gives up the uniform interface, because the meaning of each call is hidden in the payload.

The reverse also holds: following the style does not require every detail of HTTP to be used. What the constraints ask for is visible in how the interface is shaped. Does each address identify one thing? Does the method say what is wanted? Does the response say how to read it and whether it may be reused? Those questions can be put to any interface, and the answers say more about its design than the transport it happens to use.

A few neighbouring terms are worth separating. An API is any interface a program can call. A web API is one reached over the web. A REST API is a web API designed in the REST style. SOAP, a messaging protocol with its own envelope, is a different design again; SOAP vs REST compares the two with the same request.

What are REST API status codes, and when does each apply?

Status codes group by their first digit. 2xx means the request succeeded, and 4xx means the request was at fault. The exact codes carry more than the class, and a client can act on them without parsing the body. Forcing every outcome into 200 throws that information away.

Two details deserve attention. A 201 belongs with a Location header, because the client learns the address of the new resource from it. A 405 belongs with an Allow header, which RFC 9110 requires, so the client learns what it may do instead. Codes without those headers leave the client with a result and no next step.

Errors need the same care as successes. A stable, machine-readable error structure, the same on every operation, lets clients handle failures without guessing from text. How PUT and POST differ in the codes they return is worked through in PUT vs POST.

Is a RESTful API different from a REST API?

Mostly the words are interchangeable. This is an observation about usage, not a rule from a standard: people say REST API and RESTful API for the same kind of HTTP interface. The ending -ful only adds a claim, namely that the design follows the style.

The difference starts to matter when someone tests that claim. Fielding counts hypermedia as the engine of application state among the four uniform-interface constraints (section 5.1.5). Whoever asks whether a given API is RESTful therefore has to decide how strictly that list is read, and an API with resources and methods but no links from one response to the next has not met all four.

Which methods are safe and idempotent in a REST API?

RFC 9110 calls GET, HEAD, OPTIONS and TRACE safe. It defines a method as idempotent when the intended effect of several identical requests equals the effect of one. PUT, DELETE and all safe methods qualify. POST is registered as neither safe nor idempotent. The word intended matters: a server may still log every request, and the rule describes the effect the method asks for.

Safe and idempotent are statements about the method as defined, and they bind implementers. A service that changes data on a GET breaks what clients and caches assume about that method. A service that makes PUT append instead of replace breaks what every retrying client assumes.

The practical consequence appears after a failure. If a connection drops before the response arrives, a client may repeat an idempotent request without knowing whether the first one went through. Repeating a POST can create a second order. PUT vs POST follows exactly that case step by step.

How do I design and review a REST API? A checklist

The list below works as a review sheet. Each point can be checked by reading requests and responses, and a failed point usually names its own fix.

1. URIs identify stable resource concepts rather than actions.
2. HTTP methods match their defined safety and idempotency.
3. Status codes distinguish meaningful outcomes.
4. Representations declare precise media types.
5. Cache rules are explicit and safe for the data involved.
6. Conditional requests are supported where concurrent edits matter.
7. Errors have a stable, machine-readable structure.
8. The OpenAPI description matches what the service really does.
9. Payload schemas declare their versions and dialects.
10. Conversions to agent tools keep authentication and side-effect boundaries intact.

Used in practice, the list works best on real traffic: take five recorded requests and walk each through the ten points. Items three and seven are easy to test this way, because the status code and the error body are visible in every recorded response. Item eight compares the written contract with observed behaviour, and any difference there is a defect in one of the two.

Security sits beside the list, not inside it. OWASP’s REST Security Cheat Sheet covers topics such as HTTPS, access control, JWT, API keys, input validation and error handling, and each deserves its own review.

Which standards describe REST APIs and their contracts?

REST is described in Fielding’s dissertation. HTTP is specified in RFC 9110, with caching in RFC 9111.

A contract is a separate matter. OpenAPI describes the operations of an HTTP API, with their parameters, payload schemas, responses and security requirements. A valid OpenAPI document shows that an API is described, not that it follows REST. In OpenAPI the Schema Object is by default a superset of JSON Schema Draft 2020-12, and the description should name the OpenAPI version it uses. The latest published version is 3.2.1, from September 2026. Representations in XML can be described with XML Schema (XSD), a W3C language for defining a class of XML documents.

The three pieces answer different questions. Fielding’s dissertation says what the style is, RFC 9110 says how HTTP messages behave, and an OpenAPI description says what one particular service offers. Mixing them up leads to arguments in which one side quotes a style rule and the other a message format.

One more use has appeared around OpenAPI descriptions: turning operations into tools that software agents can call. An operation is not automatically a good tool. Tool descriptions have to help a model choose between operations, inputs should be bounded and described, output should be predictable, and calls that change state should keep truthful approval and risk semantics. The OpenAPI-to-MCP Readiness Analyzer checks these signals in a JSON-formatted OpenAPI description and produces a draft tool definition for review.