REST web services expose resources through a uniform interface. The architectural style separates client and server concerns, requires stateless requests, permits cacheable responses, supports layered systems and optionally enables downloaded code. These constraints are intended to improve visibility, scalability and independent evolution.
The REST constraints
Client–server separation
The user-interface concern is separated from data storage and service implementation. Each side can evolve independently while the interface contract remains stable.
Stateless interaction
Each request includes the context required for the server to understand it. Stateless does not mean that the server stores no data; it means application conversation state is not hidden between requests.
Cacheability
Responses indicate whether and how they can be reused. Correct cache controls reduce latency and server work, while incorrect caching can expose private data or stale state.
Uniform interface
Resources are identified consistently, manipulated through representations and exchanged using messages whose semantics are understandable independently of one application’s internal object model.
Resources, identifiers and representations
A resource is not a database row or class instance. It is the conceptual target identified by a URI. A representation communicates current or desired state using a media type such as JSON, XML or HTML.
GET /orders/1042 HTTP/1.1
Host: api.example.com
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
ETag: "order-1042-v7"Different representations can describe the same resource. Media types, profiles and schema contracts tell clients how to interpret the bytes.
Use HTTP semantics deliberately
| Method | Typical intent | Safety / idempotency |
|---|---|---|
| GET | Retrieve a representation | Safe and idempotent |
| POST | Submit data or create under a collection | Not generally idempotent |
| PUT | Replace state at a known URI | Idempotent |
| PATCH | Apply a partial modification | Depends on patch semantics |
| DELETE | Remove the resource mapping | Idempotent |
Status codes and headers are part of the contract. A successful response should not always be forced into 200; creation, asynchronous acceptance, no-content results and conditional requests have more precise semantics.
From representations to machine-readable contracts
XML representations can be described with XSD and checked with additional Schematron rules. JSON representations often use JSON Schema. OpenAPI connects those payload schemas to operations, parameters, security requirements and responses.
OpenAPI 3.1 aligns its Schema Object with JSON Schema Draft 2020-12 while keeping API-specific vocabulary around it. A contract should declare the OpenAPI version and any JSON Schema dialect explicitly so tools do not have to guess.
From HTTP operations to agent tools
An API operation is not automatically a good agent tool. Tool descriptions need to help a model choose among operations. Inputs should be bounded and well described. Output structure needs to be predictable. State-changing calls should retain truthful risk and approval semantics.
The OpenAPI-to-MCP Readiness Analyzer checks these signals in a JSON-formatted OpenAPI description and produces a draft tool definition for review.
REST interface review checklist
- URIs identify stable resource concepts.
- HTTP methods match their defined safety and idempotency semantics.
- Status codes distinguish meaningful outcomes.
- Representations declare precise media types.
- Cache rules are explicit and safe.
- Conditional requests are supported where concurrency matters.
- Errors have a stable machine-readable structure.
- OpenAPI descriptions match observed behavior.
- Payload schemas declare versions and dialects.
- Agent-tool conversions preserve authentication and side-effect boundaries.
Frequently asked questions
01What is a REST web service?
A RESTful web service exposes resources through a uniform interface and follows REST constraints such as stateless interaction, cacheability, layering and client-server separation.
02Is every HTTP API RESTful?
No. Using HTTP methods or returning JSON does not by itself satisfy the REST architectural constraints. The interface, resource model, representations and interaction semantics matter.
03What is a resource in REST?
A resource is an abstract concept identified by a URI. Clients exchange representations of resource state rather than directly manipulating a server-side object.
04Should REST URLs contain verbs?
Resource URIs normally identify nouns or concepts, while the HTTP method expresses the action. Process resources can still model operations when the domain requires them.
05What does stateless mean in REST?
Each request contains the information needed to understand it. The server does not rely on hidden conversational session state from earlier requests, although it can store resource state.
06How does OpenAPI relate to REST?
OpenAPI describes HTTP API operations, parameters, schemas, security and responses. It can document RESTful interfaces, but a valid OpenAPI document does not prove that an API follows REST constraints.
07Can a REST API return XML?
Yes. REST does not require JSON. A resource can have XML, JSON, HTML or other representations selected through media types and content negotiation.
08What is idempotency in an HTTP API?
An idempotent method has the same intended effect when an identical request is repeated. GET, PUT and DELETE are defined as idempotent, while POST is not generally idempotent.
09How should API errors be represented?
Use meaningful HTTP status codes, a documented error media type, stable machine-readable identifiers and human-readable detail. Keep error structure consistent across operations.
10Can OpenAPI operations become MCP tools?
They can provide a starting point. Tool conversion also requires clear descriptions, bounded inputs, structured outputs, authentication handling and accurate side-effect metadata.