# REST

> Архитектурный стиль распределённых систем, описанный Роем Филдингом в 2000 году; на практике — подход к проектированию веб-API вокруг ресурсов, URL и методов HTTP.

Источник: https://llmdocs.ru/wiki/rest/ · обновлено 2026-11-09 · лицензия CC BY-SA 4.0

- **Полное название**: Representational State Transfer
- **Автор**: Рой Филдинг
- **Год**: 2000 (диссертация, Калифорнийский университет в Ирвайне)
- **Протокол**: обычно HTTP
- **Формат данных**: чаще всего JSON
- **Описание API**: OpenAPI
- **Альтернативы**: GraphQL, gRPC, JSON-RPC
**REST** (англ. *Representational State Transfer* — «передача репрезентативного состояния») — архитектурный стиль распределённых систем, который Рой Филдинг описал в диссертации 2000 года как обобщение принципов, сделавших веб масштабируемым.[1] В повседневной речи «REST API» означает более узкую вещь: веб-API, в котором данные представлены как **ресурсы** с адресами (URL), а действия над ними выражаются стандартными методами [HTTP](https://llmdocs.ru/wiki/http.md) — `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.

REST — самый распространённый стиль публичных API: так устроены API GitHub, Stripe, облачных провайдеров и большинства внутренних сервисов.

## Происхождение

Рой Филдинг — один из авторов спецификаций HTTP/1.0 и HTTP/1.1 и сооснователь веб-сервера Apache. В главе 5 своей диссертации в Калифорнийском университете в Ирвайне он сформулировал набор ограничений, соблюдение которых даёт системе масштабируемость, независимость компонентов и простоту. Веб с его ссылками, кэшами и прокси — главный пример такой системы.

## Ограничения REST

1. **Клиент — сервер.** Интерфейс отделён от хранения данных, и стороны развиваются независимо.
2. **Отсутствие состояния** (*stateless*). Каждый запрос содержит всё необходимое для обработки; сервер не хранит контекст клиента между запросами.
3. **Кэшируемость.** Ответы явно помечаются как кэшируемые или нет — это снижает нагрузку и задержки.
4. **Единообразный интерфейс.** Ресурсы идентифицируются URL, изменяются через представления (например, [JSON](https://llmdocs.ru/wiki/json.md)), сообщения самоописательны, а переходы между состояниями задаются ссылками — **HATEOAS** (*Hypermedia as the Engine of Application State*).
5. **Многоуровневая система.** Между клиентом и сервером могут стоять прокси, балансировщики и CDN, о которых клиент не знает.
6. **Код по запросу** (необязательное). Сервер может передавать исполняемый код, например [JavaScript](https://llmdocs.ru/wiki/javascript.md).

Большинство «REST API» не соблюдают HATEOAS, поэтому сам Филдинг считает их не REST в строгом смысле. Удобная шкала — **модель зрелости Ричардсона**: уровень 0 — один адрес для всего (как в RPC), уровень 1 — отдельные ресурсы, уровень 2 — правильные методы и [коды состояния](https://llmdocs.ru/wiki/http-status-codes.md), уровень 3 — гипермедиа-ссылки. Практические API обычно останавливаются на уровне 2.[2]

## Проектирование API

Ресурсы называют существительными во множественном числе, а действие задаёт метод:

| Запрос | Действие | Типичный ответ |
|---|---|---|
| `GET /users` | список пользователей | 200 |
| `GET /users/42` | один пользователь | 200 или 404 |
| `POST /users` | создать пользователя | 201 и заголовок `Location` |
| `PUT /users/42` | заменить целиком | 200 или 204 |
| `PATCH /users/42` | изменить часть полей | 200 |
| `DELETE /users/42` | удалить | 204 |
| `GET /users/42/orders` | заказы пользователя | 200 |

```bash
curl -s https://api.example.com/v1/users?role=admin&limit=20
curl -s -X PATCH --json '{"email": "alice@example.com"}' https://api.example.com/v1/users/42
```

Соглашения, которые делают API предсказуемым:[5]

- **Фильтрация, сортировка и постраничный вывод** через параметры запроса: `?status=paid&sort=-created_at&limit=50&cursor=...`. Курсорная пагинация надёжнее смещения на больших и меняющихся наборах.
- **Версионирование** — в пути (`/v1/`) или в заголовке; ломающие изменения — только в новой версии.
- **Идемпотентность.** Для `POST`, создающих платежи и заказы, клиент передаёт заголовок `Idempotency-Key`, чтобы повтор запроса после сбоя не создал дубликат.
- **Ошибки** — подходящим кодом состояния и телом в формате Problem Details (RFC 9457).[6]
- **Безопасность** — только HTTPS, аутентификация токенами ([OAuth 2.0 и OpenID Connect](https://llmdocs.ru/wiki/oauth-oidc.md)), ограничение частоты запросов (код 429), настройка [CORS](https://llmdocs.ru/wiki/cors.md) для браузерных клиентов.

Действия, плохо ложащиеся на CRUD, оформляют как подресурсы или ресурсы-процессы: `POST /orders/42/cancel` или `POST /exports` с последующим опросом `GET /exports/7`.

## Описание API: OpenAPI

Для документирования REST API стандартом стала спецификация **OpenAPI** (бывший Swagger): машиночитаемое описание путей, параметров, схем данных и ответов в YAML или JSON.[3] По нему генерируют интерактивную документацию, клиентские библиотеки и тесты. Фреймворки вроде [FastAPI](https://llmdocs.ru/wiki/fastapi.md) строят описание OpenAPI автоматически по коду, а языковые модели и агенты используют его, чтобы понять, как вызывать API.

## REST и альтернативы

| Стиль | Особенности | Когда выбирают |
|---|---|---|
| REST | ресурсы, HTTP-семантика, кэширование | публичные API, CRUD, простота |
| [GraphQL](https://llmdocs.ru/wiki/graphql.md) | один адрес, клиент сам выбирает нужные поля | сложные клиенты с разнородными экранами |
| gRPC | двоичный Protocol Buffers поверх HTTP/2, генерация кода | связь между внутренними сервисами, потоки |
| JSON-RPC | вызов именованных методов | простые RPC-протоколы, например [MCP](https://llmdocs.ru/wiki/mcp.md) |

## См. также

- [HTTP](https://llmdocs.ru/wiki/http.md)
- [Коды состояния HTTP](https://llmdocs.ru/wiki/http-status-codes.md)
- [JSON](https://llmdocs.ru/wiki/json.md)
- [GraphQL](https://llmdocs.ru/wiki/graphql.md)
- [FastAPI](https://llmdocs.ru/wiki/fastapi.md)

## Источники

1. [Roy T. Fielding — Architectural Styles and the Design of Network-based Software Architectures, Chapter 5: REST (2000)](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)
2. [Martin Fowler — Richardson Maturity Model](https://martinfowler.com/articles/richardsonMaturityModel.html)
3. [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
4. [RFC 9110 — HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110)
5. [Microsoft — Web API design best practices](https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design)
6. [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457)