REST — архитектурный стиль для распределённых гипермедийных систем. Его ограничения не привязаны исключительно к HTTP, но на практике REST API чаще всего строят поверх HTTP. API, соответствующий ограничениям REST, называют RESTful API.
Ограничения REST
REST определяет пять обязательных ограничений и одно необязательное.
Клиент-сервер
Клиент отвечает за пользовательский интерфейс и взаимодействие с пользователем, сервер — за данные и бизнес-возможности. Такое разделение позволяет развивать и масштабировать части системы независимо.
Отсутствие состояния сессии на сервере
Каждый запрос клиента должен содержать всю информацию, необходимую серверу для его понимания и обработки. Сервер не полагается на сохранённый между запросами контекст клиентской сессии.
Это не означает, что сервер не хранит данные пользователей, не использует БД или кэш. Ограничение относится именно к контексту взаимодействия, который нужен для обработки следующего запроса.
Кэширование
Ответ должен явно или неявно определять, можно ли его кэшировать. Корректное кэширование уменьшает задержки и нагрузку, но требует учитывать актуальность и правила повторного использования ответа.
Единообразный интерфейс
Это центральное ограничение REST. Оно включает четыре части:
- идентификация ресурсов: ресурс имеет стабильный идентификатор, обычно URI;
- управление через представления: клиент получает представление ресурса и отправляет представления или инструкции для изменения его состояния;
- самоописываемые сообщения: сообщение содержит достаточно метаданных, чтобы получатель понял, как его обработать;
- hypermedia as the engine of application state (HATEOAS): ответы сообщают клиенту о доступных дальнейших действиях через ссылки и элементы управления.
Многоуровневая система
Клиент не обязан знать, взаимодействует ли он с конечным сервисом напрямую или через прокси, gateway, кэш либо другой промежуточный слой. Каждый компонент видит только соседние слои.
Код по требованию — необязательно
Сервер может временно расширять функциональность клиента, передавая исполняемый код, например JavaScript. Это единственное необязательное ограничение REST.
REST и HTTP API
Не каждый JSON API поверх HTTP является RESTful. На практике команды часто используют отдельные идеи REST — ресурсы, единообразные URI, семантику HTTP-методов и кэширование — не реализуя HATEOAS полностью. Важно явно договориться о стиле API, а не использовать слово REST как синоним любого HTTP API.
OpenAPI и Swagger
OpenAPI — машиночитаемая спецификация описания HTTP API: операций, параметров, схем данных, ответов и механизмов безопасности. Она применима не только к RESTful API.
Swagger — семейство инструментов вокруг OpenAPI, включая Swagger UI и Swagger Editor. OpenAPI — спецификация, Swagger — инструменты и историческое название спецификации до версии 3.0.