API, JSON і webhooks: простежмо одну подію між двома застосунками

Отримання повідомлення й завершення роботи — різні кроки. Ілюстрацію створено за допомогою AI.

Два застосунки обмінялися повідомленням, і хтось каже: «Інтеграція спрацювала». Що саме сталося? Повідомлення могло надійти, пройти перевірку формату або спричинити створення корисного завдання. Це різні спостереження. Простеживши одну подію, легше пов’язати терміни з доказами.

Інтерфейс визначає, як програмне забезпечення може взаємодіяти

Application programming interface, або API, надає визначені можливості й правила взаємодії програм. MDN описує його як контракт між застосунком та іншим програмним чи апаратним забезпеченням. Тому API — ширше поняття, ніж вебадреса: його інтерфейс описує взаємодію, доступну програмі.

Інтеграція поєднує застосунки у спільному процесі. Документація GitHub дає конкретний приклад цієї відмінності: інтеграція може використовувати API для запиту чи зміни даних, а webhooks — щоб дізнаватися про події. Інтеграція є робочим зв’язком; API та повідомлення про подію можуть бути його складовими.

Для конкретного зв’язку контракт має визначати значення операції, очікувану інформацію та те, що підтверджує відповідь. Поля з назвою «ready» недостатньо, якщо сторони не погодили, що саме готове й що отримувач може робити далі. Ці значення визначає архітектура застосунку.

Одна вигадана чернетка переходить до перевірки

Уявімо редакторський застосунок A і трекер перевірок B. A фіксує, що чернетка готова до перевірки. B має створити для неї завдання, яке очікуватиме перевірки. Застосунки, документ і повідомлення вигадані. Тут нічого не надсилали, не підключали й не тестували на реальному сервісі, а готовність до перевірки не означає дозволу на публікацію.

У цьому навчальному прикладі повідомлення має містити назву події, посилання на документ і додатний цілий номер версії. Подія має називатися «draft_ready». Посилання на документ має відповідати документу, який процес-отримувач має право опрацьовувати. Це наш ілюстративний контракт, а не специфікація payload постачальника.

{
  "event": "draft_ready",
  "document": "example_note",
  "revision": 2
}

JSON — скорочення від JavaScript Object Notation — текстовий формат обміну структурованими даними. У визначенні JSON від MDN описано об’єкти, масиви, рядки, числа, булеві значення та null. Приклад є невеликим об’єктом даних, а не виконуваним кодом інтеграції чи повним запитом до реального інтерфейсу.

Синтаксично коректний JSON доводить лише те, що парсер може прочитати його структуру. Заміна числової версії рядком «two» залишила б JSON коректним, але порушила б наше правило додатного цілого числа. Невідоме посилання на документ могло б мати правильний тип і не пройти бізнес-перевірку. Ні успішний розбір, ні ці перевірки полів не підтверджують повноважень відправника.

Розрізняйте прохання виконати роботу й повідомлення про подію

Запит просить інтерфейс виконати визначену операцію або повернути інформацію. Повідомлення про подію сповіщає, що щось відбулося. У вигаданому процесі «draft_ready» повідомляє про стан редакторського застосунку. Отримувачу все одно потрібне явне правило, яке пов’язує цю подію зі створенням завдання перевірки. Повідомлення не отримує необмежених повноважень лише тому, що назва події звучить корисно.

Webhook доставляє повідомлення про подію налаштованому отримувачу. У поясненні webhooks від GitHub описано підписку на події та отримання HTTP-запиту з даними події, коли вона відбувається. Ця доставка сама є запитом до отримувача; відмінність стосується значення повідомлення, а не нібито окремого виду транспорту для сповіщень.

Натомість polling періодично перевіряє API на наявність даних або змін. У випадку webhook джерело події надсилає сповіщення налаштованому отримувачу. GitHub описує цей контраст для своїх інтеграцій. Вибір схеми все одно потребує фактичних правил доставки й доступу відповідного інтерфейсу; самі терміни не обіцяють певної затримки чи повної історії подій.

У нашій вигаданій архітектурі A міг би повідомляти B про готовність чернетки, а B — дозволеним запитом отримувати її потрібні деталі. Подія та запит деталей мають різні призначення. Якщо запит не дозволяє встановити, яка версія готова, завдання перевірки має залишатися невизначеним, а не непомітно використовувати іншу версію.

Визначте, що саме доводить кожне підтвердження

У цій ілюстрації підтвердження отримання означає лише те, що повідомлення надійшло до процесу-отримувача B. Окремо зафіксований результат підтверджує існування завдання, яке очікує перевірки. Це свідомі припущення нашого прикладу, а не універсальні тлумачення HTTP-статусу чи відповіді постачальника. Інтеграція потребує спостережуваних доказів результату, який обіцяє.

Якщо підтвердження отримання не видно, результат невідомий. Перед повторним надсиланням операторам потрібні правила конкретного постачальника щодо доставки, повторів, порядку й дублікатів, а також спосіб перевірити процес-отримувач. Термін webhook не гарантує опрацювання exactly-once. У вигаданому процесі повторні сповіщення не повинні непомітно ставати запитами на додаткові перевірки.

Так само прийняття з’єднання не має стирати межі дозволів. Автентифікацію й авторизацію потрібно перевіряти за правилами конкретного інтерфейсу та застосунку. Поле JSON не може саме надати собі дозвіл на публікацію. У цьому прикладі дозволений результат B — завдання для перевіряльника; його рішення залишається наступним кроком.

Матеріал «Від AI-демонстрації до надійного робочого процесу» поширює цю ідею на навколишній процес: визначте контракт входу й виходу, зробіть збої видимими та назвіть наступну відповідальну роль. Оцінюючи результат інтеграції, запитуйте, яку межу справді пройдено — формат повідомлення, прийняття операції, отримання чи бізнес-результат, — і явно вказуйте наступний неперевірений крок.

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