Integracje API — stabilna wymiana danych między systemami

Integracje API: kontrakt OpenAPI, autoryzacja, retry, idempotencja, webhooki, monitoring, błędy i wersjonowanie.

Technologie

Definicja

Integracja API pozwala systemom wymieniać dane i uruchamiać działania według jasno określonego kontraktu.

Integracja API pozwala systemom wymieniać dane bez odtwarzania kliknięć użytkownika. Dobrze zaprojektowany kontrakt, autoryzacja, idempotencja i monitoring sprawiają, że automatyzacja jest stabilna również wtedy, gdy część systemów czasowo nie odpowiada.

Kontrakt jako umowa

Specyfikacja OpenAPI opisuje zasoby, operacje, parametry, modele danych i błędy. Kontrakt powinien być wersjonowany i testowany. Nie wystarczy odpowiedź HTTP 200, jeżeli pole obowiązkowe nagle zmieniło znaczenie albo format.

Konsument API powinien walidować odpowiedź, a producent jasno określać kody błędów, limity i zasady zgodności wstecznej.

Autoryzacja i uprawnienia

Należy stosować tożsamości techniczne, krótkotrwałe tokeny i najmniejszy wymagany zakres uprawnień. Sekrety nie mogą znajdować się w kodzie ani logach. W środowiskach Microsoft Graph wybór najmniej uprzywilejowanego zakresu jest podstawową zasadą projektową.

Autoryzacja odpowiada nie tylko na pytanie „czy klient może się połączyć”, ale także „czy może wykonać tę konkretną operację na tym zasobie”.

Retry i idempotencja

Sieć jest zawodna. Ponowienie powinno używać kontrolowanego backoffu i dotyczyć tylko błędów przejściowych. Operacja tworząca zasób musi być idempotentna albo posiadać klucz deduplikacji. W przeciwnym razie timeout po stronie klienta może doprowadzić do ponownego utworzenia zamówienia, mimo że pierwsza operacja zakończyła się sukcesem.

Webhook i zdarzenia

Webhook ogranicza potrzebę cyklicznego odpytywania, ale wymaga weryfikacji podpisu, obsługi duplikatów i możliwości ponownego pobrania zdarzenia. Zdarzenie informuje, że coś się stało; stan biznesowy warto potwierdzić w źródłowym API.

Kolejka lub broker może odseparować tempo producenta od konsumenta i ułatwić retry.

Monitoring i wersjonowanie

Należy mierzyć liczbę wywołań, błędy według klas, czas odpowiedzi, retry, odrzucone komunikaty i backlog. Logi powinny zawierać identyfikator korelacji bez ujawniania danych wrażliwych. Wersja API powinna mieć okres wsparcia i zapowiedzianą datę wycofania.

Przykład praktyczny

System zamówień wysyła POST /orders z nagłówkiem Idempotency-Key. Po timeoutcie ponawia żądanie. API rozpoznaje klucz i zwraca wcześniej utworzone zamówienie zamiast tworzyć duplikat. Zdarzenie order.accepted trafia do kolejki, a workflow aktualizuje status sprawy. Każdy krok używa wspólnego correlation_id.

Tabela decyzyjna

Tabela decyzyjna
Obszar	Wymaganie	Test
Kontrakt	OpenAPI i walidacja schematu	contract test
Autoryzacja	najmniejszy zakres	test negatywny uprawnień
Idempotencja	klucz deduplikacji	powtórzenie żądania
Retry	backoff i limit	symulacja 503/timeout
Webhook	podpis i deduplikacja	duplikat zdarzenia
Monitoring	correlation ID i metryki	śledzenie pełnej transakcji

Checklista

[ ] Kontrakt jest wersjonowany.
[ ] Zdefiniowano błędy i limity.
[ ] Uprawnienia są minimalne.
[ ] Operacje krytyczne są idempotentne.
[ ] Retry nie obejmuje błędów trwałych.
[ ] Monitoring łączy wywołania przez correlation ID.

Ryzyka i ograniczenia

Duplikaty: Ponowienie tworzy kolejny zasób.
Zbyt szerokie uprawnienia: Przejęty token daje dostęp do nadmiarowych danych.
Cichy breaking change: Zmiana pola uszkadza konsumentów.
Brak obserwowalności: Nie da się ustalić miejsca awarii.

Następny krok

Przygotuj kontrakt OpenAPI.
Zdefiniuj politykę retry i idempotencji.
Zaprojektuj dashboard integracji oraz runbook.

Źródła i data weryfikacji

Data weryfikacji źródeł: 1 sierpnia 2026 r.