REST

REST (англ. Representational State Transfer — «передача репрезентативного состояния») — архитектурный стиль распределённых систем, который Рой Филдинг описал в диссертации 2000 года как обобщение принципов, сделавших веб масштабируемым.^[1] В повседневной речи «REST API» означает более узкую вещь: веб-API, в котором данные представлены как ресурсы с адресами (URL), а действия над ними выражаются стандартными методами HTTP — 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), сообщения самоописательны, а переходы между состояниями задаются ссылками — HATEOAS (Hypermedia as the Engine of Application State).
5. Многоуровневая система. Между клиентом и сервером могут стоять прокси, балансировщики и CDN, о которых клиент не знает.
6. Код по запросу (необязательное). Сервер может передавать исполняемый код, например JavaScript.

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

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

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

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), ограничение частоты запросов (код 429), настройка CORS для браузерных клиентов.

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

Описание API: OpenAPI

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

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

См. также

• HTTP
• Коды состояния HTTP
• JSON
• GraphQL
• FastAPI

Источники

1. Roy T. Fielding — Architectural Styles and the Design of Network-based Software Architectures, Chapter 5: REST (2000)
2. Martin Fowler — Richardson Maturity Model
3. OpenAPI Specification
4. RFC 9110 — HTTP Semantics
5. Microsoft — Web API design best practices
6. RFC 9457 — Problem Details for HTTP APIs