Этап 10 - HATEOAS: обзор
HATEOAS означает Hypermedia as the Engine of Application State. Простыми словами, response может содержать links на действия, которые сейчас доступны. Ответ по заказу может включать self, cancel, pay или invoice links в зависимости от состояния заказа и прав пользователя. Многие JSON API не используют полный HATEOAS везде, но идея полезна, когда клиенту нужна discoverability или когда доступные действия зависят от состояния.
Какую проблему это решает
API design становится важным, когда от одного backend зависят несколько клиентов. Метод controller может быть простым в коде и неудобным в использовании. Клиенту нужны названия из предметной области, стабильные response bodies, предсказуемые ошибки и endpoints для списков, которые не ломаются при росте данных. Хороший дизайн API отличает сервер, который просто отвечает, от интерфейса продукта, на который команды могут безопасно опираться.
Полезно думать об этой теме через контракт. Контракт - это не только сгенерированная документация. Это обещание: request с конкретным method, path, parameters, body, authentication state и headers получит response с понятным status code и известной формой. Если backend developer меняет это обещание без осторожности, frontend, mobile app, партнерская интеграция или автоматическая job могут сломаться, хотя сервер продолжит запускаться.
Как об этом думать
Начинайте с бизнес-действия, а потом переводите его на язык API. Если пользователь хочет видеть заказы, ресурс скорее всего называется orders, а не getOrdersData. Если пользователь хочет отменить заказ, нужно понять: это изменение состояния существующего заказа, sub-resource или доменная команда, которой нужен отдельный endpoint. Решение должно быть видно в URL, method, response code и формате ошибки.
Не проектируйте “умно”. Проектируйте понятно для разработчика, который откроет API через полгода. Имена должны быть скучными и очевидными. Optional parameters должны иметь ясные значения по умолчанию. Response должен включать только то, что клиенту разрешено знать. Внутренние имена колонок, stack traces, экспериментальные enum и временные поля миграции не должны вытекать в публичный контракт случайно.
Конкретный пример
GET /api/orders?status=PAID&page=0&size=20&sort=createdAt,desc
Accept: application/json
Такой endpoint рассказывает понятную историю. Клиент просит orders, а не вызывает backend function по имени. Query parameters явные: один filter, запрос страницы и правило sorting. Сервер может проверить эти параметры, описать их в OpenAPI, вернуть стабильную форму ответа и использовать единый формат ошибки, если request неправильный.
Полезная таблица
| Понятие | Значение |
|---|---|
| self | Link на текущий ресурс |
| action link | Link на разрешенное действие |
| state | Бизнес-состояние ресурса |
| discoverability | Клиент узнает доступные действия из response |
Частые ошибки
- Проектировать endpoints от имен controller methods, а не от ресурсов.
- Возвращать наружу то, как сейчас выглядит database entity.
- Считать validation, errors, pagination и versioning деталями, которые можно добавить потом.
- Менять форму response без проверки существующих clients.
- Документировать API только после implementation, когда дизайн уже трудно менять.
Чеклист понимания
- Я могу объяснить, какой контракт endpoint дает клиенту.
- Я могу назвать request parameters и допустимые values.
- Я могу описать успешный и ошибочный response без чтения backend code.
- Я понимаю, какие изменения будут breaking для существующего client.
Практика перед следующим уроком
Добавьте полезные links в response заказа и объясните, почему каждый link есть или отсутствует.