Integracje API: od REST do OAuth.

Cztery podstawowe wzorce integracji

Po setkach integracji wychodzi kilka wzorców, które wracają niezależnie od branży:

• Sync codziennie batch: raz dziennie cron sync nowych rekordów z systemu A do B. Najtańszy, najstabilniejszy. Działa dla danych, które nie wymagają real-time (raporty, analityka, archiwum).
• Polling co X minut: workflow odpytuje API co 5-30 minut o nowe rekordy. Kompromis między real-time a kosztami. Pasuje dla większości integracji B2B.
• Webhook (push): system źródłowy wysyła callback przy każdej zmianie. Real-time, efektywny, ale wymaga, żeby system źródłowy wspierał webhooki.
• Streaming (Kafka, Kinesis): dla bardzo wysokowolumenowych integracji. Zdarzenia trafiają do topic'u, konsumenci czytają. Dla enterprise z milionami zdarzeń dziennie.

Wybór wzorca to pierwsza decyzja projektowa. Zależy od: wymagań real-time, wolumenu, możliwości systemu źródłowego, budżetu.

OAuth 2.0 w praktyce

OAuth to standard, ale każda implementacja dostawcy różni się drobnymi szczegółami. Rzeczy, które muszę uwzględnić w workflow:

• Token refresh: access token wygasa po 1-24 godzinach. Workflow musi wiedzieć kiedy refreshnąć używając refresh tokena, przechować nowy access, retry original request.
• Scope management: różne dane wymagają różnych scope. Minimalizacja jest kluczowa (principle of least privilege), ale dodanie scope post-factum wymaga re-authorizacji użytkownika.
• Multi-tenant auth: jeśli workflow obsługuje wielu klientów (np. platforma SaaS), każdy ma swój własny token. Przechowywanie tokenów per tenant w encrypted storage (nie w n8n credentials, które są per workflow).
• Rotacja refresh tokenów: niektórzy dostawcy rotują refresh token przy każdym użyciu (np. Allegro). Workflow musi update'ować stored token, inaczej następny refresh failuje.
• Revocation: jeśli użytkownik anuluje autoryzację, workflow dostaje 401. Wtedy trzeba zatrzymać workflow dla tego tenanta i alertować.

Rate limiting i backoff

Każde API ma rate limity. Workflow bez świadomości limitów w produkcji padnie.

• Poznawaj limity zawczasu: dokumentacja API zawsze podaje. Typowo: X requests per second, Y requests per hour, Z requests per day. Notuj plus zakładaj 20 procent bufora.
• Rate limiter po stronie workflow: nie wysyłaj requestów szybciej niż limit pozwala. Techniki: token bucket w Redisie, sleep-based limiter w Pythonie, n8n Rate Limit Node.
• Exponential backoff przy 429: gdy mimo limitera dostaniesz 429 Too Many Requests, cofnij się (sleep 1s, potem 2s, potem 4s...), retry. Max 5-8 prób, potem fail.
• Distributed rate limiting: jeśli masz wiele workflow'ów odpytujących to samo API, globalny rate limit (Redis-based) zapobiega ich konkurowaniu o limit.
• Respect Retry-After header: niektóre API zwracają Retry-After header wskazujący sekundy. Używaj tego zamiast własnego algorytmu, jeśli dostępny.

Błędy transientne vs permanentne

Nie każdy błąd zasługuje na retry. Klasyfikacja:

• Transientne (retry OK): 429 (rate limit), 500 (serwer error), 502/503/504 (gateway issues), network timeouts. Wszystkie powinny być retry z backoff.
• Permanentne (retry bez sensu): 400 (bad request), 401 (unauthorized, token issue), 403 (forbidden, scope issue), 404 (not found, resource zniknął), 422 (validation error). Retry nie pomoże, trzeba naprawić request albo alertować.
• Ambiguous: 409 (conflict), 412 (precondition failed). Zależy od kontekstu. Typowo nie retry bez zmiany requestu.

Workflow pattern: try plus catch, klasyfikacja błędu, retry dla transientnych, alert dla permanentnych, DLQ (dead letter queue) dla tych, które powracają N razy.

Monitoring integracji w produkcji

Bez monitoringu nie wiesz, że integracja zaczęła padać, dopóki klient nie zadzwoni. Minimum produkcyjne:

• Metryki per integracja: liczba requestów, success rate, average latency, błędy per typ. Eksportowane do Prometheus, dashboard w Grafana.
• Alerting na spadki: success rate spadł poniżej 95 procent → alert. Latency wzrosła o 50 procent → alert. Error rate wzrósł → alert.
• Structured logging: każde wywołanie API logowane z correlation ID, żeby można było śledzić pojedynczy request przez wiele systemów. JSON format dla parsowalności (Loki, Elasticsearch, CloudWatch Insights).
• Synthetic monitoring: cron workflow co 5 minut, który testuje krytyczne integracje (fake request, sprawdzenie odpowiedzi). Działa nawet gdy prawdziwy ruch zanika.
• Historia zmian API: dostawca zmienił format response? Tracking wersji API (header X-API-Version albo URL v1/v2) plus automatyczne alerty jeśli schema się różni od oczekiwanej.

Najczęstsze pytania

Co warto przeczytać obok