Каждый второй разработчик называет своё API «RESTful». Каждый второй из этих — неправ.

Я тоже так делала. Берёшь Express, накидываешь эндпоинтов — /api/users, /api/orders — и говоришь коллегам: «у нас REST API». Звучит солидно. Но однажды меня спросили: «А где у тебя гипермедиа? HATEOAS?»

Откуда это пошло

REST придумал Рой Филдинг в 2000 году. Его диссертация — программная архитектура для распределённых гипермедиа систем. Он описал шесть ограничений:

  • Клиент-сервер — разделение ответственности
  • Без состояния — сервер не хранит состояние клиента между запросами
  • Кэширование — ответы могут кэшироваться
  • Единообразие интерфейса — унифицированный способ обращения к ресурсам
  • Слои — можно добавлять прокси и балансировщики
  • HATEOAS — самая спорная часть: сервер возвращает ссылки на связанные ресурсы

Большинство API, которые мы называем REST, нарушают последнее ограничение. И это нормально.

Что реально используется

На практике существуют три уровня «зрелости» API по модели Ричардсона:

Уровень 0 — один URL, все операции через POST с параметром «action». RPC-стиль, не REST.

Уровень 1 — ресурсы разделены по URL: /users, /orders. Уже лучше, но только HTTP-метод — POST для всего.

Уровень 2 — правильные HTTP-методы: GET для чтения, POST для создания, PUT/PATCH для обновления, DELETE для удаления. Статусы: 200, 201, 404, 500. Вот это и есть то, что большинство компаний называет REST.

Уровень 3 — HATEOAS. Сервер возвращает ссылки:

{"id": 42, "name": "Креативия", "links": [{"rel": "orders", "href": "/users/42/orders"}, {"rel": "self", "href": "/users/42"}]}

Этот уровень используют GitHub API (частично), некоторые Stripe-эндпоинты. Большинство — не использует.

Почему HATEOAS не прижился

Филдинг говорит, что без HATEOAS у вас не REST, а «REST API» (с кавычками). Но:

  • Клиенты стали сложнее — проще передать документацию и схему, чем генерировать ссылки
  • Frontend-фреймворки (React, Vue) требуют предсказуемый ответ — они не парсят ссылки динамически
  • Кэширование на уровне CDN работает лучше, если клиент явно запрашивает ресурс

Что использовать на практике

Называйте вещи своими именами:

  • «HTTP API» — если используете REST-стиль (ресурсы + правильные методы)
  • «REST API» — только если возвращаете HATEOAS-ссылки
  • «JSON API» — если придерживаетесь спецификации JSON:API
  • «RPC» — если у вас один эндпоинт с экшенами

Это не про снобизм. Это про точность коммуникации. Когда на собеседовании спрашивают «Что такое REST?» — полезно знать реальный ответ, а не маркетинговый.

Мораль: не обязательно следовать всем правилам Филдинга, чтобы делать хорошие API. Но полезно понимать, какие правила вы сознательно нарушаете и почему.