Lista kontrolna integracji API
0) Szybka recenzja (kto co robi)
- Przypisany właściciel integracji
- Wymagane są kontakty dyżurne (24 × 7/godziny pracy)
- Uzgodnione SLO/SLA i Release Support Window
- Strona stanu i kanał incydentów (e-mail/slack/webhook)
1) Dostęp, środowiska, wersje
- Dostęp do piaskownicy/postoju/produkcji
- Wersja API potwierdzona: '/v1 '/nagłówek 'X-API-Version'
- Zezwalaj na konfigurowanie zasad IP i sieciowych
- Zegar i TZ: wszystkie razy w UTC, synchronizacji NTP
- Sprawdzona kompatybilność SemVer SDK/klienta i matryca wersji
2) Uwierzytelnianie i żetony
- Uzgodniony mechanizm OAuth2 Poświadczenia klienta/Auth Code + PKCE/API Key/mTLS
- Dostęp Token Lifetime i odświeżenie Token Rotation Configured
- Dla API Key: secret is shown once, stored in the secret manager
- JWKS/WIT/„ dziecko ”sprawdzone, skok zegara na ± 5 min
- Nagłówki „autoryzacji” nie są rejestrowane (wersja)
bash curl -sS -H "Authorization: Bearer $TOKEN" https://api. example. com/v1/ping3) Bezpieczeństwo i prywatność
- TLS 1. 2 +/HSTS, opcjonalnie mTLS
- Minimalizacja PII: wysyłamy tylko to, czego potrzebujemy, maski w dziennikach
- Udokumentowana polityka zachowania i dyspozycji (RODO/DSAR)
- Tajna rotacja: aktywny/następny klucz, plan przewrócenia
- Przeciwdziałanie nadużyciom: Captcha/Prędkość klucza/Ograniczenia rejestracji
4) Limity, kwoty i zaległości
- Zadeklarowane nagłówki 'X- Limit- '/' X-Quota-'
- Klient szanuje 429 i „Retry-After”
- Przekładki tylko dla 5xx/408/429, wykładnicze backoff + jitter
- Zestaw czasowy/powtórny (np. ≤ 5 prób, ≤ 60c ogółem)
5) Idempotencja i konflikty
- Wszystkie operacje zapisu są wysyłane za pomocą 'Idempotency-Key' (TTL ≥ 24-72 h)
- Duplikat Conflict → 409 IDEMP_REPLAY obsługiwane
- ETag/„ If-Match ”włączone do aktualizacji konkurencyjnych (jeśli są dostępne)
bash curl -X POST /v1/payments \
-H "Idempotency-Key: pay-<uuid>" \
-d '{"amount":"12. 34","currency":"EUR"}'6) Paginacja i przyrostowe delty
- zastosowana paginacja kursora/klawisza („next _ cursor”, „has _ more”)
- Stabilny rodzaj „(updated_at, id)” udokumentowany
- Przesyłki przyrostowe: znak wodny lub żeton zmiany
- Nakładanie się (nakładanie się 1-2 min) i dedup przez '(id, wersja/seq)'
7) Format błędu i diagnostyka
- Jednolity format „application/problem + json” (RFC 7807)
- Wsparcie w terenie: "error _ code", "trace _ id'," retriable "," detailed "
- Opisano mapę błędów i działania klienta (runbook)
json
{
"type":"https://docs. example. com/errors/validation_failed",
"title":"Validation failed",
"status":422,
"error_code":"VAL_001",
"trace_id":"a1b2c3",
"retriable":false
}8) Haki internetowe: potwierdzenia i powtórki
- Potwierdzenie sukcesu - dowolne 2xx; szybki ACK po zapytaniu
- Модбиса HMAC ("X-Signature: sha256 =..."), "X-Webhook-Id'," X-Retry "
- Polityka retray: backoff + jitter, do 24-72 godzin
- DLQ + Replay: Dostępne i zatwierdzone
- Pamięć dedup w odbiorniku, TTL ≥ okna retray
9) Obserwowalność i śledzenie
- Haki OpenTelemetry włączone w kliencie/SDK
- Korelacja śladu _ id/X-Request-ID w całym łańcuchu
- Даборна: 'requests _ total', 'errors _ total {status}', 'latency _ p95', 'retry _ count',' 429 _ rate'
- Alarmy: 5xx/429 spike, wzrost p95, spadek szybkości sukcesu, opóźnienie haka internetowego
promql rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])10) Wydajność i stabilność
- Baseny połączeń, utrzymać przy życiu, HTTP/2/3 w miarę możliwości
- Backpressure, kolejka klienta nie jest „napompowana”
- skonfigurowane zasady wyłącznika/timeout/fallback
- Badania obciążenia: wybuch 10 ×, długie połączenia, zimny start
11) Dane, waluty, czas
- Formaty: ISO-8601 UTC, pieniądze - ciągi dziesiętne/niewielkie jednostki, lokalizacje nie zależą od środowiska
- Kodowania/języki są spójne (np. „Akceptuj język” dla wiadomości, ale „error _ code” dla maszyny)
- Udokumentowana polityka zaokrąglania/prowizji
12) Pojednanie
- Dzienne/godzinne uzgodnienia z kontrolami
- API/przesłania dla przebadanych pojednań (CSV/JSON, manifesty/hashes)
- Rozbieżności - w biletach z odniesieniami do „trace _ id”
13) Zgodność i aspekty prawne
- Akceptowane warunki stosowania API (sprawiedliwe użycie/kontrola wywozu)
- PII/Posiadacze danych - Role i obszary przechowywania zdefiniowane
- Legalne przechowywanie/rejestrowanie audytu Działania włączone w przypadku incydentów
14) Dokumentacja i portal deweloperski
- OpenAPI/AsyncAPI są istotne, istnieją przykłady „copy-pasty”
- SDK (TS/Py/Java/Go/.NET) - wersje są spójne, Cookbook jest dostępny
- Wypróbuj prace na placu zabaw, klucze piasku są aktywne
- Zmiany/spadki/mapa drogowa są widoczne w portalu
15) Testowanie: funkcjonalne, negatywne, chaos
Funkcjonalne
- Przeszedł scenariusz CRUD/key (szczęśliwa ścieżka)
- Pagination/Cursor/Incremental Deltas
Negatywne
- 401/403/404/409/422/429/5xx i przetwarzanie „Retry-After”
- Nieprawidłowy podpis haka, utracone żetony, duże ciała
Chaos
- Spadek 10-30% zdarzeń, reorder, 1-10 min opóźnień
- Wyłączenie zależności (PSP/KYC) → poprawne awaryjne/błędy
16) Odbiór i uruchomienie (go-live)
- Ostateczny raport PRR (przegląd gotowości produkcji) przeszedł
- Włączenie kanaryjskie: 10% → 25% → 50% → 100%
- Auto-rollback na sygnałach SLO (błędy/opóźnienia/429)
- Matryca kontaktowa incydentu i ścieżka eskalacji Opublikowano
- Zaległości CAPA po wygenerowaniu pilota
17) Obsługa i wsparcie
- Runbook/playbooks: "5xx spike", "429 storm'," webhook backlog "," timeout "
- Regularne sprawozdania z budżetu SLO/błędów
- Obrotowe sekrety i klucze na harmonogramie
- Uzgodniona wersja planu depresji/migracji (data wygaśnięcia)
18) Wzory artefaktów
Szablon do oprogramowania,
yaml api:
base_url: https://api. example. com/v1 timeout_ms: 10000 retries: { max: 5, strategy: expo-jitter }
auth:
kind: oauth2 token_url: https://auth. example. com/oauth2/token scopes: [wallet:read, wallet:write]
webhooks:
secret_ref: secret/webhook-hmac parallelism: 10 max_body_kb: 256Polityka retray (pseudo)
json
{"initial":1,"max":60,"factor":2. 0,"jitter":0. 2,"retriable":["5xx","408","429"]}19) Lista kontrolna końcowa „do podpisu”
- Środowiska/wersje/klucze/lista dopuszczalna gotowa
- Auth/JWT/klawisze/mTLS skonfigurowane i przetestowane
- Wdrożono limity/kwoty/przekłady/idempotencję
- Pagination/cursor/deltas work on data
- Haki internetowe: Podpisy, Powtórki, Zweryfikowany DLQ/Replay
- Problem błędów + json „,” trace _ id' przylega do wszystkich dzienników
- Zbierane deski rozdzielcze/wpisy, OTel włączony
- Przeszedł testy obciążenia/negatywnego/chaosu
- Uzgodnienia i raporty zbiegają się, zakłady są formalizowane
- PRR/canary/rollback-plan gotowy, wskazane kontakty dyżurne
Razem
Ta lista kontrolna obejmuje techniczne, operacyjne i zgodne aspekty integracji API. Przejdź przez elementy od góry do dołu, zautomatyzuj limity sprawdzania, idempotencję i haki webowe, umożliwiaj obserwowalność i plan rollback - a Twój start będzie przewidywalny, bez „niespodzianek” w produkcji.