API, інтерфейс прикладного програмування, - це просто задокументований спосіб, у який одна частина програмного забезпечення може попросити іншу частину програмного забезпечення про дані або зробити так, щоб щось сталося. Коли CRM надсилає новий контакт на платформу електронної пошти, або електронний магазин надсилає замовлення в систему обліку, вони використовують API.
Три поширені шаблони
Запит / відповідь
Одна система запитує, інша відповідає: "дай мені цього клієнта", "створи це замовлення". Просто й передбачувано, але вимагає, щоб одна сторона знала, коли запитувати.
Вебхуки
Замість того, щоб запитувати повторно, система-джерело надсилає подію на URL, коли щось відбувається: "створено новий рахунок", "платіж успішний". Нижча затримка та більша ефективність для подієво-керованих потоків.
Планована синхронізація
Періодичні завдання переміщують дані пакетами - щогодини, щоночі, щотижня. Корисно, коли свіжість не критична, а надсилання непрактичне.
Більшість реальних інтеграцій поєднують щонайменше два з цих підходів.
Що робить інтеграцію надійною
- Чітке володіння даними. Одна система є джерелом істини для кожної частини даних. Інші отримують копії.
- Ідемпотентні операції. Повторення того самого виклику двічі дає той самий результат - суттєво для вебхуків та нестабільних мереж.
- Видима обробка помилок. Збої потрапляють кудись, де їх може побачити людина, а не в тихий лог, який ніхто не читає.
- Дотримання обмежень швидкості. Хороші інтеграції відступають, коли інша сторона повільна або обмежена.
- Усвідомлення версіонування. API змінюються. Розглядайте інтеграцію як код, що потребує оновлень, а не одноразове підключення.
Що робить інтеграцію крихкою
- CSV-експорти, що розсилаються поштою по компанії та повторно імпортуються вручну.
- Жорстко закодовані облікові дані в місцях, які ніхто не пам’ятає.
- Один довгий скрипт, що робить усе без логіки повторних спроб.
- Тихі збої - дані перестають надходити, і ніхто не помічає тижнями.
- Двостороння синхронізація без чітких правил конфліктів: яка сторона перемагає, коли обидві змінилися?
Middleware чи пряма інтеграція?
Є три основні підходи:
- Пряма інтеграція: система A спілкується безпосередньо із системою B. Найпростіше для одного зв’язку, стає безладним, коли їх багато.
- Інтеграційна платформа (iPaaS): спеціальний інструмент, як-от workflow-платформа, обробляє конектори. Добре для простих, поширених потоків; може бути дорогим та непрозорим для складної логіки.
- Індивідуальний middleware: невеликий внутрішній сервіс, що володіє логікою інтеграції, трансляціями та обробкою помилок. Часто правильний вибір, коли логіка специфічна для бізнесу.
Найкраща відповідь залежить від того, скільки систем мають спілкуватися одна з одною, скільки задіяно індивідуальної логіки і чи хочете ви, щоб бізнес-правила були в інтерфейсі постачальника чи в коді, яким володієте ви.
Конкретний приклад вебхука
Скажімо, платформа електронної комерції має сповіщати вашу систему обліку щоразу, коли замовлення оплачено. Замість опитування щохвилини магазин викликає вашу кінцеву точку з невеликим JSON-навантаженням:
{
"event": "order.paid",
"event_id": "evt_8f3c21a9",
"occurred_at": "2024-11-12T09:41:07Z",
"order": {
"id": "ORD-10427",
"total": 1499.00,
"currency": "PLN",
"customer_email": "k.nowak@example.com"
}
}Сервіс-отримувач має прийняти запит, перевірити заголовок підпису, зберегти event_id і швидко повернути 200. Власне робота, як-от створення рахунку, відбувається у фоновому завданні. Якщо та сама подія надходить двічі, збережений event_id запобігає дублюванню рахунку.
Правило великого пальця: обробники вебхуків мають швидко підтверджувати та виконувати роботу асинхронно. Усе повільне чи крихке - виклик стороннього API, рендеринг PDF - належить до черги, а не до HTTP-обробника.
Обробка повторних спроб без дублів
Кожна надійна інтеграція потребує ключа ідемпотентності. Мінімальний шаблон у псевдокоді:
async function handleOrderPaid(event) {
if (await seen(event.event_id)) return; // already processed
await markSeen(event.event_id);
await queue.enqueue('create-invoice', event.order);
}Поширені помилки
- Інтеграція надто рано. Якщо процес нестабільний, інтеграція закодує безлад і ускладнить зміни.
- Двостороння синхронізація за замовчуванням. Одностороння простіша й часто достатня - переходьте на двосторонню лише якщо бізнес справді цього потребує.
- Відсутність моніторингу. Інтеграція без сповіщень - це тихий збій, що чекає, щоб статися.
- Тісне зчеплення. Зміни в одній системі не повинні ламати всі інші. Тримайте рівень трансляції.
Реалістичний підхід
- Намалюйте потік даних: яка система володіє яким полем і кому потрібні копії.
- Почніть із найболіснішого окремого потоку і збудуйте його спершу одностороннім.
- Використовуйте вебхуки там, де важлива низька затримка, плановану синхронізацію - там, де ні.
- Додайте моніторинг з першого дня, а не після першого збою.
- Задокументуйте облікові дані, кінцеві точки та володіння, щоб інтеграція пережила зміни персоналу.
