Что такое HATEOAS и стоит ли реализовывать его в типичном внутреннем REST API?

Короткий ответ

HATEOAS (Hypermedia as the Engine of Application State) — принцип, при котором ответ API включает ссылки на доступные дальнейшие действия/ресурсы, позволяя клиенту "навигировать" по API динамически, а не хардкодить все URL заранее; для большинства внутренних и даже публичных API практическая польза ограничена по сравнению с ростом сложности, и решение внедрять его зависит от того, насколько клиентам нужна такая динамическая навигация.

Как это работает подробнее

вместо того чтобы клиент заранее знал, что после получения заказа со статусом "ожидает оплаты" нужно обратиться к /orders/{id}/pay, сервер включает в ответ ссылку с этим URL (и, возможно, только если действие действительно доступно в текущем состоянии) — клиент просто следует ссылкам, а не хардкодит бизнес-логику переходов.

Пример кода

example.jsonКопировать

{
  "id": 42,
  "status": "awaiting_payment",
  "links": {
    "self": "/orders/42",
    "pay": "/orders/42/pay",
    "cancel": "/orders/42/cancel"
  }
}
{
  "id": 42,
  "status": "paid",
  "links": {
    "self": "/orders/42",
    "refund": "/orders/42/refund"
  }
}

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

• Рекомендация. HATEOAS добавляет реальную ценность, когда переходы между состояниями ресурса действительно сложны и часто меняются, а разные клиенты (в том числе написанные не вами) должны адаптироваться к этим изменениям без пересборки — например, в API с богатым workflow заказов. Для большинства внутренних API, где клиент и сервер разрабатываются и деплоятся одной командой с полным контролем над обеими сторонами, выгода от динамической навигации не оправдывает дополнительную сложность реализации и тестирования — такие решения принимаются исходя из реального числа независимых клиентов и частоты изменения workflow, а не "потому что это настоящий REST".

Подводные камни

• Риски. внедрять HATEOAS "для соответствия стандарту REST" без реальных клиентов, которые бы использовали эти ссылки динамически, что добавляет сложность без практической выгоды; либо наоборот — полностью игнорировать идею и хардкодить в клиенте бизнес-правила о допустимых переходах состояний, которые было бы правильнее получать от сервера, если они часто меняются.