Уровни зрелости Ричардсона

Урок показывает, как измерить «насколько RESTful» ваш API, по четырёхступенчатой шкале Леонарда Ричардсона.

Модель зрелости Ричардсона — это шкала из четырёх уровней (0–3), описывающая, насколько API использует возможности REST: ресурсы, HTTP-глаголы, статусы и гиперссылки.

«RESTful» — не выключатель, а градиент. Между «совсем не REST» и «идеальный REST» есть промежуточные ступени. Леонард Ричардсон предложил разложить путь к REST на четыре уровня, где каждый добавляет одну ключевую идею. Эта модель — отличный инструмент, чтобы честно оценить свой API и понять, что улучшить.

Уровень 0: один URI, всё через POST

Самый примитивный уровень — это «HTTP как туннель». Есть один-единственный адрес, на который шлют все запросы методом POST, а что именно нужно сделать, описано внутри тела. HTTP здесь используется лишь как транспорт; его возможности игнорируются.

POST /api HTTP/1.1
Content-Type: application/json

{"action": "getUser", "id": 42}

Хотите создать пользователя? Тот же адрес, другое действие в теле:

{"action": "createUser", "name": "Анна"}

Так устроены старые RPC-стили и SOAP. Снаружи невозможно понять, что происходит: и чтение, и удаление — это POST /api. Ни кэш, ни прокси не могут помочь, потому что для них все запросы одинаковы.

Уровень 1: ресурсы

На первом уровне появляется ключевая идея REST — много адресов вместо одного. Каждая сущность получает свой URL. Вместо одной «свалки» /api возникают /users/42, /orders/7, /products/3.

POST /users/42       (получить пользователя)
POST /orders/7       (получить заказ)

Прогресс есть: мы разделили «вещи». Но метод всё ещё один (POST), и что мы делаем с ресурсом — читаем, меняем, удаляем — по-прежнему спрятано в теле. Уровень 1 — это «разделяй и властвуй» по адресам, но без понятных операций.

Уровень 2: HTTP-глаголы и статусы

Здесь живёт большинство реальных «REST API». Появляются две вещи: разные HTTP-методы для разных операций и осмысленные коды статусов.

Теперь действие задаётся не телом, а методом:

GET    /users/42     получить пользователя
POST   /users        создать пользователя
PUT    /users/42     заменить пользователя
DELETE /users/42     удалить пользователя

И сервер отвечает осмысленным кодом статуса, а не всегда 200:

Это даёт огромную пользу: GET можно безопасно кэшировать и повторять (он ничего не меняет), прокси понимают семантику, а клиент по коду статуса сразу знает исход. Большинство API, которые называют себя RESTful, останавливаются ровно здесь — и для практики этого, как правило, достаточно.

Уровень 3: HATEOAS

Вершина модели — HATEOAS (Hypermedia As The Engine Of Application State). Идея: ответ сервера содержит не только данные, но и ссылки на следующие возможные действия. Клиент не должен «зашивать» URL в код — он берёт их из ответа, как человек кликает по ссылкам на сайте.

{
  "id": 7,
  "status": "new",
  "total": 1200,
  "_links": {
    "self":   {"href": "/orders/7"},
    "pay":    {"href": "/orders/7/pay"},
    "cancel": {"href": "/orders/7/cancel"}
  }
}

Клиент видит: этот заказ можно оплатить или отменить, и вот по каким адресам. Если заказ уже оплачен, сервер просто не пришлёт ссылку pay — и клиенту не нужно самому знать правила. Это делает API самоописываемым и устойчивым к изменениям URL. На практике уровень 3 встречается редко: он сложнее в реализации, а выгоду получают не все клиенты.

Как работает под капотом

Соберём всю шкалу в одну картину — что добавляет каждый уровень:

  Уровень 0  -->  один URI, один POST        (HTTP как туннель)
  Уровень 1  -->  + много ресурсов (URL)      (разделили вещи)
  Уровень 2  -->  + HTTP-глаголы и статусы    (понятные операции)
  Уровень 3  -->  + ссылки в ответах HATEOAS  (самоописание)

Каждая ступень добавляет ровно одну идею и опирается на предыдущую. Важно понимать назначение модели: это не оценка «хорошо/плохо». Уровень 2 — совершенно нормальный, зрелый выбор для большинства проектов. Модель Ричардсона нужна, чтобы говорить о REST точнее: вместо спора «RESTful это или нет» можно сказать «это уровень 2, без HATEOAS» — и всем понятно, о чём речь.

Где находится «типичное REST API»? Почти всегда на уровне 2: ресурсы с URL, правильные методы GET/POST/PUT/DELETE и осмысленные коды статусов. Это разумный баланс пользы и сложности, и именно его мы будем проектировать в этом курсе.

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

• Считать уровень 3 обязательным для «настоящего REST». На практике подавляющее большинство хороших API — уровня 2. HATEOAS полезен, но не бесплатен.
• Останавливаться на уровне 0–1 и называть это REST. Если всё идёт через POST /api с действием в теле — это RPC, а не REST, как бы его ни называли.
• Воспринимать шкалу как оценку качества. Это шкала использования возможностей HTTP, а не «плохой/хороший». Уровень 2 часто оптимален.
• Игнорировать коды статусов на уровне 2. Возвращать всегда 200 с полем error внутри — значит не доползти до уровня 2 по-настоящему.

Итог

• Модель Ричардсона — шкала 0–3, измеряющая, насколько API использует REST.
• Уровень 0: один URI, всё через POST (HTTP как туннель).
• Уровень 1: ресурсы получают отдельные URL.
• Уровень 2: разные HTTP-глаголы и осмысленные коды статусов — здесь живёт большинство API.
• Уровень 3: HATEOAS — ссылки на действия прямо в ответах; редкость на практике.
• Шкала — инструмент описания, а не оценка «хорошо/плохо»; уровень 2 обычно оптимален.