API, czyli interfejs programistyczny aplikacji, to po prostu udokumentowany sposób, w jaki jeden program może poprosić inny o dane lub o wykonanie akcji. Gdy CRM wysyła nowy kontakt do systemu mailingowego, a sklep internetowy posyła zamówienie do księgowości, używają API.

Trzy typowe wzorce

Żądanie / odpowiedź

Jeden system pyta, drugi odpowiada: „podaj mi tego klienta”, „utwórz to zamówienie”. Proste i przewidywalne, ale wymaga, żeby pytająca strona wiedziała, kiedy zapytać.

Webhooki

Zamiast ciągle pytać, system źródłowy sam wysyła zdarzenie pod wskazany adres: „utworzono fakturę”, „płatność zaakceptowana”. Niska latencja, naturalne dla przepływów opartych na zdarzeniach.

Synchronizacja cykliczna

Zadania wsadowe przenoszące dane co godzinę, noc lub tydzień. Sensowne, gdy świeżość nie jest krytyczna, a push jest niepraktyczny.

W realnych wdrożeniach zwykle łączy się co najmniej dwa z tych wzorców.

Co czyni integrację niezawodną

• Jasne właścicielstwo danych. Jeden system jest źródłem prawdy dla każdego pola. Pozostałe dostają kopie.
• Operacje idempotentne. Powtórzenie tego samego wywołania daje ten sam efekt, kluczowe przy webhookach i niestabilnej sieci.
• Widoczne obsłużenie błędów. Awarie trafiają tam, gdzie zobaczy je człowiek, a nie do logu, którego nikt nie czyta.
• Szacunek dla rate limitów. Dobre integracje wycofują się, gdy druga strona zwalnia lub limituje.
• Świadomość wersji API. API się zmieniają. Integracja to kod, nie „jednorazowe podpięcie”.

Co czyni integrację kruchą

• Eksporty CSV, które krążą po firmie mailem i są ręcznie importowane.
• Zaszyte hasła w miejscach, o których nikt już nie pamięta.
• Jeden długi skrypt robiący wszystko bez retry.
• Ciche awarie, dane przestają płynąć, nikt tego nie widzi przez tygodnie.
• Dwukierunkowa synchronizacja bez reguł konfliktu: która strona wygrywa, gdy obie zmieniły rekord?

Middleware czy integracja bezpośrednia?

Trzy główne podejścia:

• Integracja bezpośrednia: system A rozmawia bezpośrednio z B. Najprostsze dla jednej relacji, zaczyna się plątać przy wielu.
• Platforma integracyjna (iPaaS): dedykowane narzędzie workflow z konektorami. Dobre do prostych, typowych przepływów; bywa drogie i nieczytelne przy złożonej logice.
• Własne middleware: mała wewnętrzna usługa, która trzyma logikę integracji, mapowania i obsługę błędów. Często słuszny wybór, gdy logika jest specyficzna dla firmy.

Najlepsza odpowiedź zależy od liczby systemów, ilości własnej logiki i tego, czy wolicie mieć reguły biznesowe w UI dostawcy czy w kodzie pod własną kontrolą.

Konkretny przykład webhooka

Załóżmy, że sklep internetowy ma powiadamiać system księgowy przy każdym opłaconym zamówieniu. Zamiast odpytywać co minutę, sklep wywołuje wasz endpoint z krótkim payloadem 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"
  }
}

Serwis odbiorczy powinien przyjąć żądanie, zweryfikować podpis w nagłówku, zapisać event_id i szybko zwrócić 200. Właściwa praca, np. wystawienie faktury, dzieje się w zadaniu w tle. Jeśli to samo zdarzenie przyjdzie dwa razy, zapisany event_id zapobiegnie zduplikowanej fakturze.

Retry bez duplikatów

Każda rzetelna integracja potrzebuje klucza idempotencji. Minimalny wzorzec w pseudokodzie:

async function handleOrderPaid(event) {
  if (await seen(event.event_id)) return; // już obsłużone
  await markSeen(event.event_id);
  await queue.enqueue('create-invoice', event.order);
}

Najczęstsze błędy

• Integracja zbyt wcześnie. Jeśli proces nie jest stabilny, integracja zakoduje bałagan i utrudni jego zmianę.
• Dwukierunkowość domyślnie. Jednokierunkowość jest prostsza i zwykle wystarcza, dwukierunkową wprowadzajcie tylko wtedy, gdy jest naprawdę potrzebna.
• Brak monitoringu. Integracja bez alertów to cicha awaria czekająca, aż się wydarzy.
• Mocne sprzężenie. Zmiana w jednym systemie nie powinna łamać pozostałych. Trzymajcie warstwę tłumaczącą.

Realistyczne podejście

1. Narysujcie przepływ danych: który system jest właścicielem którego pola i komu należy się kopia.
2. Zacznijcie od najbardziej bolącego przepływu, jednokierunkowo.
3. Webhooki tam, gdzie liczy się latencja; synchronizacja wsadowa tam, gdzie nie.
4. Monitoring od pierwszego dnia, nie po pierwszej awarii.
5. Udokumentujcie dostęp, endpointy i właścicielstwo, żeby integracja przetrwała zmiany kadrowe.