Що таке HATEOAS і чи потрібен він у реальних API?

HATEOAS (Hypermedia as the Engine of Application State) - обмеження REST, за яким клієнт не знає URL наперед, а знаходить наступні можливі дії в посиланнях з відповідей, як людина переходить за посиланнями на сайті.

{
  "id": 42,
  "status": "pending",
  "total": 1250,
  "_links": {
    "self":   { "href": "/orders/42" },
    "pay":    { "href": "/orders/42/payments", "method": "POST" },
    "cancel": { "href": "/orders/42/cancel", "method": "POST" }
  }
}

Після оплати посилання pay зникне, а з'явиться, наприклад, invoice. Клієнт не вирішує сам, чи можна скасувати замовлення, - він бачить, чи є посилання cancel.

Рой Філдінг наполягав: API без гіпермедіа - не REST. Тому більшість «REST API» в його термінах насправді «HTTP API».

Що обіцяє HATEOAS:

• сервер може змінювати URL без оновлення клієнтів;
• бізнес-правила на сервері: клієнт показує кнопку «Скасувати», лише якщо є посилання, - логіку дозволених переходів не дублюють у мобільному застосунку й фронтенді;
• самоописуваність: API можна «досліджувати».

Чому на практиці його використовують рідко:

• клієнти все одно знають домен: мобільний застосунок «знає», що в замовлення є оплата, і має для неї окремий екран. Він не будує інтерфейс динамічно з посилань;
• URL і так стабільні й задокументовані в OpenAPI; генеровані клієнти працюють зі статичними шляхами;
• накладні витрати: розмір відповідей, складність серверу, слабка підтримка інструментами;
• немає єдиного стандарту формату посилань (HAL, JSON:API, Siren, JSON-LD).

Що з HATEOAS корисно взяти навіть без повної реалізації:

• посилання пагінації (next, prev) - ресурси Laravel додають їх автоматично. Курсорну пагінацію інакше й не реалізувати зручно;
• прапорці дозволених дій у відповіді - практичний компроміс: "can": {"cancel": true, "refund": false} - клієнт не повторює правила авторизації;
• Location після створення і посилання на асинхронний статус (202 + URL задачі).

JSON:API (Laravel 13 має вбудований JsonApiResource) включає links у стандарт - це найпоширеніший спосіб отримати частину переваг гіпермедіа без власного формату.

Докладніше в документації: Рой Філдінг: REST API мають керуватися гіпертекстом