HATEOAS – “Hypermedia As The Engine Of Application State” – Гіпермедіа як двигун стану програми

Що таке HATEOAS?

Hypermedia as the Engine of Application State, або скорочено HATEOAS, — це різновид REST, яка використовує гіпермедіа для опису майбутніх дій, доступних клієнту. Дозволені дії виводяться в API на основі поточного стану програми та повертаються клієнту як набір посилань. Потім клієнт використовує ці посилання для подальшої взаємодії з API.

Чи потрібен мені HATEOAS, щоб зробити REST?

На мій погляд, ні. Тепер це потенційно суперечлива точка зору, оскільки багато хто буде стверджувати, що лише сервіси з підтримкою гіпермедіа дійсно RESTful. Я будую свою думку на досвіді в реальному світі та тому факті, що протягом багатьох років я створював численні REST API, які не використовували HATEOAS, але добре служили своїй меті. HATEOAS, звичайно, має своє місце, але його не слід вважати обов’язковим для RESTful API.

Різні ступені заповненості REST

На даний момент я вважаю, що варто поглянути на REST на високому рівні, щоб побачити, куди підходить HATEOAS. Модель зрілості Річардсона надає гарний огляд, розбиваючи архітектурний стиль REST на різні рівні зрілості. Ці рівні визначають, наскільки RESTful є система, починаючи з нульового рівня і працюючи до рівня 3.

  • Нульовий рівень описує систему, яка використовує HTTP лише як транспортний механізм, також відомий як тунелювання URI. Один URI та дієслово HTTP зазвичай використовуються для всіх взаємодій із звичайним старим XML, що надсилається через мережу. Старий шкільний SOAP-RPC є хорошим прикладом нульового рівня.
  • Перший рівень описує систему, яка будується на нульовому рівні, вводячи поняття ресурсів. Ресурси зазвичай представляють бізнес-об’єкт і зазвичай описуються за допомогою іменників. Кожен ресурс адресується через унікальний URI, а для всіх взаємодій використовується єдине дієслово HTTP.
  • Другий рівень будується на першому, використовуючи ширший діапазон HTTP-дієслів для взаємодії з кожним ресурсом. Зазвичай GET, POST, PUT і DELETE використовуються для отримання, створення, оновлення та видалення ресурсів, надаючи споживачам поведінку CRUD для кожного ресурсу.
  • Третій рівень розвивається на другому, представляючи HATEOAS. Гіпермедійні посилання використовуються для надання клієнту списку можливих майбутніх дій. Список дій формується в API на основі поточного стану програми.

Наведена нижче діаграма підсумовує модель зрілості Річардсона. 

Назва зображення
модель зрілості Річардсона

У цій публікації ми розглянемо рівень 3, гіпермедійні послуги. Ми розглянемо HATEAOS у простому API, який працює з клієнтами, замовленнями та продуктами. Ми почнемо з перегляду деяких зразків відповідей HATEAOS, а потім перейдемо до реалізації простого гіпермедійного API 

Як виглядає HATEOAS?

Отже, як саме виглядає HATEOAS? Давайте розглянемо зразок відповіді виклику GET до Customer API. Як і слід було очікувати, відповідь містить JSON-представлення Клієнта але також містить колекцію гіпермедійних посилань.  

{
    "customerId": 1,
    "firstName": "Joe",
    "lastName": "Smith",
        "dateOfBirth": "1982-01-10",
        "address": {
            "id": 1,
            "street": "High Street",
            "town": "Newry",
            "county": "Down",
            "postcode": "BT893PY"
        },
        "links": [{
                "rel": "self",
                "href": "http://localhost:8080/api/customer/1"
        }, {
                "rel": "update",
                "href": "http://localhost:8080/api/customer/1"
        }, {
                "rel": "delete",
                "href": "http://localhost:8080/api/customer/1"
        }, {
                "rel": "orders",
                "href": "http://localhost:8080/api/customer/1/orders"
        }]
}

Кожне посилання має два атрибути.

  • rel —  описує зв’язок між  ресурсом клієнта  та URL-адресою (атрибут href). Rel по суті описує дію, яка виконується з посиланням. Важливо, щоб це значення було інтуїтивно зрозумілим, оскільки воно описує мету посилання. 
  • href  — URL-адреса, яка використовується для виконання дії, описаної у  відн .

У наведеному вище прикладі перше посилання має значення rel self  і вказує, що href є посиланням на поточний ресурс клієнта . Іншими словами, якщо клієнт хоче отримати свіжу копію цього клієнта  , він може скористатися посиланням, пов’язаним із self . Наступні два посилання мають значення rel update і delete відповідно. Вони досить інтуїтивно зрозумілі та, як і слід було очікувати, надають посилання на кінцеві точки для оновлення та видалення поточного  ресурсу клієнта . Останнє посилання має порядки відносних значень і описує посилання, яке отримує всі пов’язані з цим ресурси Order Замовник .

Використання Hypermedia для навігації API

Після того, як клієнт отримав Клієнта, він може використовувати гіпермедіа у відповіді для подальшої взаємодії з API. Посилання надають список можливих дій, доступних клієнту. Посилання у прикладі JSON вище дозволяють клієнту оновлювати, видаляти або отримувати нову копію Cutomer Клієнт також може отримати список Замовлень , пов’язаних із Клієнтом . 

На діаграмі нижче описано просту подорож через API. Клієнт починає із отримання ресурсу клієнта , а потім використовує посилання на замовлення , щоб отримати список пов’язаних замовлень. Нарешті, клієнт використовує посилання «Продукти» , щоб отримати всі продукти , пов’язані із  замовленням . Клієнт може переходити через API від  клієнта до його замовлень , а потім до продуктів , пов’язаних із цим замовленням. 

Назва зображення

Зачекайте, я не маю всієї потрібної інформації! 

На цьому етапі ви могли помітити, що надані посилання не містять усієї інформації, необхідної для навігації API. Подивіться на себе ,  оновіть і видаліть посилання у відповіді клієнта . URL-адреси однакові, але це не означає, що self  і delete повинні використовувати методи запиту GET і DELETE відповідно.

Добре, тож ви можете навести аргумент, що self і delete є прямими, оскільки вони інтуїтивно відображаються на дієслова HTTP, але було б поганою ідеєю припускати, що клієнти розуміють, як слід використовувати посилання. Уявіть, що у нас є посилання  deleteCustomerOrder . Що саме робить ця операція з точки зору клієнта? Це видаляє зв’язок між клієнтом і  замовленням чи взагалі видаляє ресурс замовлення ? Відповідь полягає в тому, що ми просто не знаємо, і немає способу надати таку інформацію через гіпермедіа. Ось де документація API вступає в гру.

HATEOAS повідомляє клієнту, які варіанти доступні в певний момент часу. Він не говорить їм, як слід використовувати кожне посилання чи яку саме інформацію слід надсилати. Важливо розуміти, що хоча HATEOAS допомагає клієнтам досліджувати ваш API, він не є заміною документації API. Потрібна документація, щоб пояснити семантику кожного посилання ( атрибут rel ) і як слід використовувати пов’язану URL-адресу. Таку інформацію, як тип вмісту, модель даних і тип запиту, все ще потрібно описати в документації API.

Чи варто використовувати HATEOAS?

Коли справа доходить до архітектурного вибору, завжди є компроміси. Перш ніж розглянути можливість використання HATEOAS у дикій природі, вам потрібно розглянути всі плюси та мінуси та чи дійсно він вам потрібен. Лише тоді ви зможете прийняти обґрунтоване рішення щодо того, чи виправдані додаткові зусилля та складність у вашому проекті.

Деякі позитиви

Готові URL-адреси

Коли URL-адреси жорстко закодовані в клієнті, зміна структури URL-адреси API вносить критичні зміни. Однією з переваг HATEOAS є те, що структуру URL-адреси API можна змінити, не впливаючи на клієнтів. Якщо структуру URL-адреси змінено в сервісі, клієнти автоматично підберуть нову структуру URL-адреси через гіпермедіа.

Можливість оновлювати API (навіть якщо це лише структура URL-адреси) без внесення критичних змін є гарною перевагою. Це особливо важливо для API із великою кількістю клієнтів, де потрібно уникнути збоїв і витрат, пов’язаних із порушенням роботи. З іншого боку, якщо ваш REST API використовується внутрішньо однією або двома вашими власними програмами, то таку критичну зміну можна впоратися швидко, і, ймовірно, це не є великою проблемою.

Explorable API 

Гіпермедійні API можна досліджувати. Посилання надають клієнту список операцій, які можна викликати на основі поточного стану програми. Це корисно для розробників клієнтів, оскільки це може допомогти їм створити кращу розумову модель API та того, як його слід використовувати.  

Як згадувалося раніше, документація API все ще потрібна для опису семантики кожного посилання разом із важливою інформацією, як-от структура повідомлення запиту, тип запиту та тип вмісту.

API стилю робочого процесу 

HATEOAS особливо добре підходить для API, які обробляють кілька кроків як частину шляху користувача або робочого процесу. Гіпермедіа — це потужний спосіб скеровувати клієнтів до наступного кроку в робочому процесі, надаючи лише посилання, релевантні на основі поточного стану програми.

Деякі негативи 

Додаткова складність

HATEOAS ускладнює API, що впливає як на розробника API, так і на тих, хто його використовує. Розробник API повинен виконувати додаткову роботу з додавання посилань до кожної відповіді та надання правильних посилань на основі поточного стану програми. Це призводить до створення програми, складнішої для створення та тестування, ніж ванільний CRUD REST API. 

Клієнтам API також доводиться мати справу з додатковою складністю гіпермедіа. Окрім розуміння семантики кожного посилання, вони мають додаткові дані для аналізу та обробки в кожній відповіді. Хоча переваги, ймовірно, переважують вартість складності на стороні клієнта, варто мати на увазі, що ваше рішення використовувати HATEOAS призведе до певної складності для клієнтів API.    

      0 0 голосів
      Рейтинг статті
      Підписатися
      Сповістити про

      Цей сайт використовує Akismet для зменшення спаму. Дізнайтеся, як обробляються ваші дані коментарів.

      0 Коментарі
      Старіші
      Новіші Найпопулярніші
      Вбудовані Відгуки
      Переглянути всі коментарі