REST архитектурный стиль
Этот материал поясняет понятие REST с примерами, вопросами и тегами.
В двух словах
REST это архитектурный стиль для распределённых гипермедиа систем на базе HTTP. Основная идея: ресурсы адресуются через URI, манипулируются стандартными методами и передаются в виде представлений.
Краткое техническое описание
REST определяет шесть ограничений: Client-Server, Stateless, Cacheable, Uniform Interface, Layered, опционально Code on Demand. Ресурсы это бизнес-объекты, уникально идентифицируемые через URI (например https://api.shop.de/orders/42). Представления передают состояние, обычно JSON или XML, согласуются через Content Negotiation с использованием заголовков Accept и Content-Type. Методы имеют семантику: GET безопасен и идемпотентен, POST не идемпотентен, PUT идемпотентен, PATCH не обязательно идемпотентен, DELETE идемпотентен. Статус-коды сигнализируют результат (200, 201, 204, 400, 401, 403, 404, 409, 500). HATEOAS встраивает ссылки навигации и действия в представления. Эффективное кэширование использует Cache-Control, ETag, Last-Modified и условные запросы.
Ключевые моменты для экзамена
- Ресурсо-ориентированный дизайн API, существительные/множественное число, стабильные URI, без глаголов в пути
- HTTP методы и семантика, безопасные/идемпотентные/не-идемпотентные, маппинг на CRUD
- Чётко определить идемпотентность, особенно для PUT, DELETE, POST с Idempotency Key
- Целенаправленное использование статус-кодов, 2xx/3xx/4xx/5xx, Location заголовок при 201
- Требования к защите данных, логированию, отслеживаемости, документирование кодов ошибок
- Принудительный TLS, OAuth 2/OIDC, JWT, CORS, Rate Limiting, валидация входных данных, логирование
- Слабая связанность, переиспользуемость, независимое развитие клиента и сервера
- OpenAPI документация, примеры запросов/ответов, каталог ошибок, стратегия версионирования
Основные компоненты
- Дизайн ресурсов и URI
- Представления, типы медиа и схемы
- Семантика методов: GET, POST, PUT, PATCH, DELETE
- Статус-коды и заголовки
- Content Negotiation: Accept, Content-Type, Accept-Language
- Кэширование: Cache-Control, ETag, Last-Modified, Conditional Requests
- Безопасность: аутентификация, авторизация, TLS, CORS
- Версионирование: URI, заголовки, Content-Types
- Наблюдаемость: логирование, метрики, трассировка, Correlation ID
- Тестирование: Contract Tests, API Tests, тесты ошибок, тесты идемпотентности
Практический пример
// Пример: ресурс заказа с HATEOAS и идемпотентностью
Ресурсы:
GET /orders - список заказов
POST /orders - создать новый заказ
GET /orders/{order-id} - прочитать один заказ
PUT /orders/{order-id} - полностью заменить заказ
PATCH /orders/{order-id} - частично изменить заказ
DELETE /orders/{order-id} - удалить заказ
Пример POST запроса:
{
"customerId": 12345,
"items": [{ "sku": "A1", "qty": 2 }]
}
Ответ 201 Created, заголовок: Location: https://api.shop.de/orders/42
Тело:
{
"order-id": 42,
"status": "created",
"links": [
{ "rel": "self", "href": "https://api.shop.de/orders/42" },
{ "rel": "confirm", "method": "POST", "href": "https://api.shop.de/orders/42/confirm" }
]
}
Идемпотентность в POST: клиент отправляет дополнительно Idempotency-Key: abc-123.
Сервер сохраняет результат для каждого ключа, при повторении возвращает тот же ответ.
Плюсы и минусы
Плюсы
- Интероперабельность через стандарты
- Слабая связанность, хорошая масштабируемость благодаря stateless архитектуре
- Эффективное кэширование, чёткие сигналы об ошибках через статус-коды
- Простота использования с браузерами и инструментами
Минусы
- Возможны overfetching и underfetching
- Сложные процессы записи требуют чистой идемпотентности и стратегий транзакций
- HATEOAS часто игнорируется
- Ответственность за безопасность в основном на разработчике API
- Chatty APIs увеличивают latency
Типичные вопросы экзамена (с кратким ответом)
- Шесть REST ограничений и их воздействие? Client-Server (независимая разработка), Stateless (без сессионного состояния), Cacheable (повторные ответы эффективны), Uniform Interface (стандартизированные методы), Layered (промежуточные узлы возможны), Code on Demand (опционально скрипты).
- PUT vs PATCH в плане идемпотентности? PUT полностью заменяет и идемпотентен, PATCH частично изменяет и не обязательно идемпотентен.
- Safe для HTTP методов? Safe означает без побочных эффектов изменения состояния, GET и HEAD безопасны (только чтение).
- ETag и условные запросы? Сервер отправляет ETag, клиент отправляет If-None-Match, при совпадении сервер отвечает 304 Not Modified без тела.
- Версионирование REST API? URI версии (/v1), на основе заголовков, Accept-based (application/vnd.firma.resource.v2+json), важно: обратно совместимые изменения.
- HATEOAS и его достоинства? Клиент обнаруживает действия через ссылки в представлениях, снижает связанность и жёсткие предположения о workflow’ах.
- Content Negotiation на практике? Клиент отправляет Accept (application/json), сервер выбирает подходящее представление или отвечает 406 Not Acceptable.
- Идемпотентные операции записи при платежах? POST на ресурс коллекции с Idempotency Key, выделенный ресурс транзакции, повторения с одинаковым ключом дают одинаковый конечный результат:
/payments/{payment-id}