RESTful API

RESTful API (Representational State Transfer Application Programming Interface) — это архитектурный стиль взаимодействия компонентов распределённого приложения в сети, основанный на наборе принципов и ограничений, определяющих, как клиентские и серверные приложения обмениваются данными. REST (сокр. от англ. Representational State Transfer, «передача репрезентативного состояния») был предложен в 2000 году Роем Филдингом (Roy Fielding) в его докторской диссертации как альтернатива более сложным протоколам, таким как SOAP. RESTful API использует протокол HTTP в качестве транспортного уровня и оперирует с ресурсами, представленными в форматах JSON, XML, HTML или других.

Основные принципы и ограничения

Архитектура REST основана на шести ключевых ограничениях (constraints), которые отличают её от других подходов к построению API:

Клиент-серверная архитектура (Client-Server)

Система разделяется на две части: клиент (пользовательский интерфейс) и сервер (хранилище данных и бизнес-логика). Клиент не заботится о хранении данных, а сервер — о пользовательском интерфейсе. Это позволяет разрабатывать и масштабировать компоненты независимо.

Отсутствие состояния (Stateless)

Каждый запрос от клиента к серверу должен содержать всю информацию, необходимую для его обработки. Сервер не хранит никакой информации о состоянии клиента между запросами (сессионные данные). Это повышает надёжность и масштабируемость, но требует передачи аутентификационных токенов или других данных при каждом запросе.

Кэширование (Cacheability)

Ответы сервера должны явно указывать, могут ли они быть кэшированы клиентом или промежуточными прокси-серверами. Правильное кэширование снижает нагрузку на сервер и уменьшает задержки.

Единообразие интерфейса (Uniform Interface)

Фундаментальное ограничение, упрощающее архитектуру. Включает четыре подпринципа:

• Идентификация ресурсов — каждый ресурс (например, пользователь, товар, заказ) имеет уникальный идентификатор (URI).
• Манипуляция ресурсами через представления — клиент работает с представлением ресурса (JSON, XML), а не с самим ресурсом. Сервер может менять внутреннюю реализацию, не меняя API.
• Самодокументируемые сообщения — каждое сообщение содержит достаточно информации, чтобы клиент мог понять, как его обработать (например, ссылки на связанные ресурсы — HATEOAS).
• Hypermedia as the Engine of Application State (HATEOAS) — клиент динамически переходит по ссылкам, предоставленным сервером, а не использует жёстко заданные пути. Это делает API самоописываемым и позволяет серверу менять структуру без нарушения работы клиентов.

Многоуровневая система (Layered System)

Архитектура может состоять из нескольких иерархических слоёв (балансировщики нагрузки, прокси-серверы, шлюзы). Каждый слой взаимодействует только с соседними, что повышает масштабируемость и безопасность.

Код по требованию (Code on Demand, опционально)

Сервер может временно расширять функциональность клиента, передавая исполняемый код (например, JavaScript-скрипты). Это единственное опциональное ограничение.

HTTP-методы и работа с ресурсами

RESTful API использует стандартные HTTP-методы для выполнения операций над ресурсами. Каждый метод имеет определённую семантику:

Идемпотентность означает, что повторное выполнение одного и того же запроса приводит к тому же состоянию сервера (например, повторный DELETE не вызовет ошибку, а просто вернёт 404). Безопасность — метод не изменяет состояние сервера.

Примеры URI и методов

• GET /users — получить список всех пользователей.
• GET /users/123 — получить пользователя с ID 123.
• POST /users — создать нового пользователя (тело запроса содержит JSON с данными).
• PUT /users/123 — полностью обновить пользователя 123.
• PATCH /users/123 — частично обновить пользователя 123 (например, только email).
• DELETE /users/123 — удалить пользователя 123.

Форматы представления данных

Наиболее распространённые форматы для обмена данными в RESTful API:

• JSON (JavaScript Object Notation) — лёгкий, удобочитаемый, поддерживается большинством языков программирования. Стандарт де-факто.
• XML (eXtensible Markup Language) — более тяжёлый, но используется в корпоративных системах и устаревших интеграциях.
• YAML — реже, но применяется в конфигурационных файлах и некоторых API.
• HTML — для API, которые возвращают готовые фрагменты веб-страниц (например, для серверного рендеринга).

Клиент указывает желаемый формат через HTTP-заголовок Accept, сервер — через Content-Type.

Статус-коды HTTP

RESTful API использует стандартные HTTP-статус-коды для информирования клиента о результате запроса. Основные группы:

• 2xx (Успех):
• 200 OK — успешный GET, PUT, PATCH, DELETE.
• 201 Created — успешный POST (создание ресурса).
• 204 No Content — успешный DELETE или PUT/PATCH без тела ответа.
• 3xx (Перенаправление):
• 301 Moved Permanently — ресурс перемещён на новый URI.
• 304 Not Modified — кэшированный ответ актуален.
• 4xx (Ошибка клиента):
• 400 Bad Request — некорректный синтаксис запроса.
• 401 Unauthorized — требуется аутентификация.
• 403 Forbidden — доступ запрещён.
• 404 Not Found — ресурс не найден.
• 405 Method Not Allowed — метод не поддерживается для данного URI.
• 409 Conflict — конфликт (например, попытка создать дубликат).
• 422 Unprocessable Entity — семантическая ошибка (например, невалидные данные).
• 5xx (Ошибка сервера):
• 500 Internal Server Error — неожиданная ошибка сервера.
• 503 Service Unavailable — сервер временно недоступен.

Версионирование API

По мере развития API его интерфейс может меняться. Чтобы не нарушать работу старых клиентов, применяют версионирование. Основные подходы:

• Версия в URI: https://api.example.com/v1/users, https://api.example.com/v2/users.
• Версия в заголовке: Accept: application/vnd.example.v1+json.
• Версия в параметре запроса: https://api.example.com/users?version=1`.