# REST (Representational State Transfer)

REST (Representational State Transfer) is an architectural style for designing networked applications, introduced by Roy Fielding in his 2000 doctoral dissertation. It defines a set of constraints for building scalable, loosely coupled web services. APIs that follow REST principles are called RESTful APIs, and they have become the dominant approach for building web APIs.

## REST constraints

A truly RESTful architecture adheres to six constraints:

1. **Client-server separation**: The client and server are independent. The client handles the user interface, while the server manages data storage and business logic.
2. **Statelessness**: Each request from the client must contain all the information needed to process it. The server does not store session state between requests.
3. **Cacheability**: Responses must indicate whether they can be cached. Proper caching reduces unnecessary network calls and improves performance.
4. **Uniform interface**: Resources are identified by URIs, manipulated through representations (typically JSON), and self-descriptive messages. Hypermedia links in responses can guide clients to related resources (HATEOAS).
5. **Layered system**: The architecture can include intermediary layers (such as API gateways, load balancers, or caches) without the client needing to know about them.
6. **Code on demand** (optional): Servers can extend client functionality by sending executable code, such as JavaScript.

## RESTful API design in practice

Most production REST APIs follow these conventions:

* **Resources as nouns**: URLs represent resources (e.g., `/users`, `/orders/42`) rather than actions.
* **HTTP methods as verbs**: GET retrieves, POST creates, PUT replaces, PATCH updates partially, DELETE removes.
* **Standard status codes**: 200 for success, 201 for created, 400 for bad request, 401 for unauthorized, 404 for not found, 500 for server error.
* **JSON payloads**: While REST does not mandate a format, JSON is the standard for modern APIs.
* **Versioning**: APIs are versioned via URL paths (`/v1/users`) or headers to allow backward-compatible evolution.

## REST vs. other API styles

* **SOAP**: More rigid, XML-based, with built-in standards for security and transactions. REST is lighter and more flexible.
* **GraphQL**: Allows clients to request exactly the data they need from a single endpoint. REST uses multiple endpoints with fixed response structures.
* **gRPC**: Uses Protocol Buffers and HTTP/2 for high-performance binary communication. Suited for internal service-to-service calls where REST's human-readable format is less important.

## REST and API gateways

REST's layered system constraint explicitly anticipates intermediary components like API gateways. A gateway sits between clients and REST services, handling concerns that are orthogonal to business logic: authentication, rate limiting, CORS, request transformation, and routing.

Serverless API Gateway is designed around REST conventions. Its configuration defines paths and HTTP methods that map to upstream servers. Each path entry specifies the allowed methods, the target backend, authorization requirements, and any variable mapping needed to transform the request. This makes it straightforward to place the gateway in front of RESTful services without changing the API contract that clients depend on.

## Related documentation

* [Path Routing](/configuration/paths.md) - Define RESTful routes with HTTP method matching
* [Servers Configuration](/configuration/servers.md) - Configure upstream REST API servers
* [CORS Configuration](/configuration/cors.md) - Handle cross-origin requests for REST APIs
* [Authorizer Configuration](/configuration/authorizer.md) - Protect REST endpoints with JWT authentication


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.serverlessapigateway.com/glossary/r/rest-representational-state-transfer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.