Принципы REST

Мы знаем, что Web API — это HTTP-запросы к URL, возвращающие данные. Но как именно называть URL? Как разграничить операции чтения, создания, удаления? Здесь вступает REST — архитектурный стиль, который задаёт правила построения предсказуемых API.

Что такое REST

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

REST не говорит «делай вот так». Он говорит: если будешь соблюдать эти ограничения, твой API будет масштабируемым, надёжным и понятным.

Ресурсы и их представления

Центральное понятие REST — ресурс. Всё, чему можно дать имя — ресурс:

Пользователь → ресурс /users/42
Список товаров → ресурс /products
Комментарий к статье → ресурс /articles/5/comments/12

Ресурс — это НЕ сами данные в базе. Это абстракция. Один и тот же ресурс может быть представлен в разных форматах (JSON, XML, HTML) — это называется представлениями (representations). Отсюда и название: Representational State Transfer.

Ограничения REST (ключевые)

1. Клиент-серверная архитектура. Клиент (браузер) и сервер разделены. Клиент отвечает за UI, сервер — за данные. Они общаются только через API. Это позволяет развивать их независимо.

2. Без состояния (Stateless). Каждый запрос содержит ВСЮ необходимую информацию. Сервер не хранит состояние клиента между запросами:

Плохо (stateful):  «дай мне СЛЕДУЮЩУЮ страницу товаров»   (сервер должен помнить, что ты смотрел)
Хорошо (stateless): «дай мне товары 21–40»                  (вся информация в запросе)

Stateless делает сервер проще: любой экземпляр может обработать любой запрос — балансировка нагрузки работает без sticky-сессий.

3. Кэширование. Сервер явно указывает, можно ли кэшировать ответ (Cache-Control). Клиенты и промежуточные прокси могут использовать кэш, снижая нагрузку на сервер.

4. Единообразие интерфейса (Uniform Interface). Самое важное ограничение. Четыре подпринципа:

Ресурсы идентифицируются URL. /users/42 — конкретный пользователь, /users — коллекция.
Представления ресурсов манипулируются через обмен представлениями. Клиент получает JSON-представление, модифицирует и отправляет обратно.
Самоописательные сообщения. Каждый запрос и ответ содержит всё необходимое для обработки: Content-Type, Authorization, Cache-Control.
HATEOAS (Hypermedia as the Engine of Application State). Ответы содержат ссылки на связанные ресурсы:

{
  "id": 42,
  "name": "Иван",
  "links": {
    "orders": "/users/42/orders",
    "cart": "/users/42/cart"
  }
}

HATEOAS редко полностью реализуется на практике, но идея важная: клиент не должен «знать» URL заранее — сервер сам подсказывает.

5. Слоёная система (Layered System). Между клиентом и сервером могут быть промежуточные слои: балансировщик, кэш, API-шлюз, файрвол. Клиент не знает, общается ли он с конечным сервером или с промежуточным — и это позволяет масштабировать систему.

Ресурсы и коллекции в URL

RESTful API строит URL по предсказуемым правилам:

GET    /users            → коллекция (список пользователей)
GET    /users/42         → элемент (конкретный пользователь)
GET    /users/42/orders  → подколлекция (заказы пользователя)
POST   /users            → создать нового пользователя
PUT    /users/42         → заменить пользователя полностью
PATCH  /users/42         → частично обновить пользователя
DELETE /users/42         → удалить пользователя

Коллекции — всегда во множественном числе (users, а не user). Элементы идентифицируются ID в URL, а не в query-параметрах. Отношения выражаются через вложенность URL (/users/42/orders).

Что НЕ является REST

Часто API называют RESTful, нарушая ключевые ограничения:

НЕ REST:  GET /api?action=getUser&id=42        (действие в параметрах, а не ресурс в URL)
НЕ REST:  POST /api/createUser                 (глагол в URL вместо HTTP-метода)
НЕ REST:  GET /users/delete/42                 (DELETE должен быть HTTP-методом, а не частью URL)
RESTful:  GET /users/42                        (ресурс в URL, метод — HTTP-глагол)

Бывают случаи, когда «не REST» оправдано — например, сложные поиски (POST /search с фильтрами в теле) или RPC-подобные действия (POST /orders/42/cancel). Это нормально, просто не REST.

Проверь себя

Что означает Stateless в контексте REST?
Почему коллекции называют во множественном числе (/users, а не /user)?
Как RESTful API различает чтение, создание и удаление ресурса?

<details> <summary>Ответы</summary>

Сервер не хранит состояние клиента между запросами. Каждый запрос содержит всю информацию для обработки. Это упрощает масштабирование.
Конвенция: /users — коллекция (список), /users/42 — элемент. Множественное число для коллекции семантически точнее и предсказуемее.
Через HTTP-методы, а не через URL: GET (чтение), POST (создание), PUT/PATCH (обновление), DELETE (удаление). Один и тот же URL /users/42 обслуживает все операции.

</details>

Что унести с урока

REST — архитектурный стиль с ограничениями: клиент-сервер, stateless, кэширование, единообразие интерфейса.
Ресурсы идентифицируются URL, операции — HTTP-методами (GET/POST/PUT/DELETE).
Stateless: каждый запрос самодостаточен, сервер не помнит клиента.
RESTful URL: коллекции (/users), элементы (/users/42), подколлекции (/users/42/orders).

В следующем уроке разберём JSON — формат, в котором REST API передаёт данные: синтаксис, типы данных, вложенные структуры и почему он стал стандартом.

Принципы REST