REST: принципы и ограничения

REST (Representational State Transfer) — архитектурный стиль для распределённых систем, описанный Роем Филдингом в диссертации 2000 года как набор из шести ограничений.

Зачем нужно

Понимание принципов REST, а не только «GET/POST/DELETE», объясняет почему правила именно такие. Statelessness позволяет масштабировать сервисы горизонтально; Uniform Interface делает API предсказуемым для любого клиента; Cacheability снижает нагрузку на сервер.

Где используется

  • Любой веб-API, претендующий называться RESTful
  • Оценка зрелости API по Richardson Maturity Model
  • Архитектурные решения при проектировании микросервисов
  • Документирование и ревью существующих API

Шесть ограничений REST

1. Client-Server (разделение клиента и сервера)

Клиент управляет UI ←→ Сервер управляет данными

Клиент не знает, как хранятся данные (SQL/NoSQL/файлы)
Сервер не знает, как данные отображаются
→ Можно менять фронтенд без изменения бэкенда и наоборот

2. Stateless (без состояния)

# ❌ Stateful — сервер помнит сессию
GET /api/next-page HTTP/1.1
# Сервер знает, на какой странице находится клиент

# ✅ Stateless — каждый запрос самодостаточен
GET /api/products?page=3&limit=20 HTTP/1.1
Authorization: Bearer eyJhbG...
# Все данные для выполнения запроса — в самом запросе

3. Cacheable (кэшируемость)

# Сервер указывает, можно ли кэшировать ответ
HTTP/1.1 200 OK
Cache-Control: public, max-age=3600
ETag: "abc123"

# Клиент повторно использует кэш без запроса на сервер
GET /api/products/42
If-None-Match: "abc123"
→ 304 Not Modified (данные не изменились)

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

Четыре подпринципа:
1. Идентификация ресурсов через URI: /api/users/42
2. Манипуляция через представления: JSON-тело, а не SQL
3. Самоописывающие сообщения: Content-Type, Accept заголовки
4. HATEOAS: ответ содержит ссылки на связанные действия

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

Клиент → Load Balancer → CDN → API Gateway → Сервис → БД
       |__________________________|
       Клиент не видит внутренней топологии

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

Сервер может отправить исполняемый код клиенту
Например: JavaScript-бандл, апплет
Единственное необязательное ограничение

Richardson Maturity Model

Уровень 0 — HTTP как транспорт: POST /api всё через один endpoint
Уровень 1 — Ресурсы: /api/users, /api/orders
Уровень 2 — HTTP-методы: GET, POST, PUT, DELETE + коды ответов
Уровень 3 — HATEOAS: ответы содержат ссылки на действия

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

  • Over-fetching — клиент получает лишние поля (решение: GraphQL, sparse fieldsets)
  • Under-fetching — нужно несколько запросов для одного экрана (решение: BFF, GraphQL)
  • Версионирование — добавление v2 в URL или заголовки создаёт дублирование
  • Real-time — REST не подходит для двусторонней связи (WebSocket, SSE)

Частые ошибки

  • Нарушение Stateless: хранение состояния клиента на сервере (в памяти процесса)
  • Глаголы в URL: /api/getUsers — нарушает Uniform Interface
  • Игнорирование кодов ответов: всегда 200, даже при ошибках
  • Называть любой HTTP API «RESTful», не соблюдая принципы

Связанные темы

Ресурсы