API tümleştirme kontrol listesi

0) Hızlı inceleme (kim ne yapar)

• Entegrasyon Sahibi Atandı
• Çağrı üzerine kişiler (24 × 7/çalışma saatleri) reçete edilir
• Anlaşmalı SLO/SLA ve Sürüm Destek Penceresi
• Durum sayfası ve olay kanalı (e-posta/slack/webhook)

1) Erişimler, ortamlar, sürümler

• sandbox/evreleme/üretim erişildi
• API sürümü onaylandı:'/v1'/header 'X-API-Version'
• IP ve ağ kurallarının yapılandırılmasına izin ver
• Saat ve TZ: UTC'de tüm zamanlar, NTP senkronizasyonu
• SemVer SDK/İstemci Uyumluluğu ve Sürüm Matrisi Doğrulandı

2) Kimlik doğrulama ve belirteçler

• Mekanizma kabul edildi OAuth2 İstemci Kimlik Bilgileri/Auth Kodu + PKCE/API Anahtarı/mTLS
• Access Token Ömür Boyu ve Yenileme Token Rotasyonu Yapılandırıldı
• API Anahtarı için: gizli bir kez gösterilir, gizli yöneticide saklanır
• JWKS/JTI/'çocuk 'kontrol edildi, saat eğrildi ± 5 dakika
• 'Yetkilendirme' başlıkları kaydedilmedi (revizyon)

bash curl -sS -H "Authorization: Bearer $TOKEN" https://api. example. com/v1/ping

3) Güvenlik ve gizlilik

• TLS 1. 2 +/HSTS, isteğe bağlı mTLS
• PII minimizasyonu: sadece ihtiyacımız olanı gönderiyoruz, günlüklerdeki maskeler
• Saklama ve Elden Çıkarma Politikası (GDPR/DSAR) belgelenmiştir
• Gizli rotasyon: aktif/sonraki anahtar, rollover planı
• Kötüye Kullanım Karşıtı: Captcha/Anahtarlama Hızı/Kayıt Kısıtlamaları

4) Sınırlar, kotalar ve geri alma

• Bildirilen 'X-RateLimit-'/' X-Quota-' başlıkları
• Müşteri 429 ve 'Retry-After'a saygı duyuyor
• Sadece 5xx/408/429 için retrays, üstel geri alma + jitter
• Yeniden deneme/zaman sınırı seti (örneğin ≤ 5 yeniden deneme, ≤ 60c toplam)

5) İdempotans ve çatışmalar

• Tüm yazma işlemleri 'Idempotency-Key'ile gönderilir (TTL ≥ 24-72 saat)
• Duplicate Conflict - 409 IDEMP_REPLAY Handled
• ETag/' If-Match 'rekabetçi güncellemeler için etkinleştirildi (varsa)

bash curl -X POST /v1/payments \
-H "Idempotency-Key: pay-<uuid>" \
-d '{"amount":"12. 34","currency":"EUR"}'

6) Pagination ve artımlı deltalar

• imleç/anahtar kümesi sayfalama kullanılır ('next _ cursor', 'has _ more')
• Kararlı sıralama '(updated_at, id)' belgelenmiştir
• Artımlı yüklemeler: filigran veya değişim belirteci
• Çakışmalar (çakışma 1-2 dk) ve dedup tarafından '(id, version/seq)'

7) Hata formatı ve tanılama

• Tekdüze format 'uygulama/problem + json' (RFC 7807)
• Alan desteği: 'error _ code', 'trace _ id', 'receivable', 'details'
• Hata haritası ve açıklanan istemci eylemleri (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) Webhooks: onaylar ve tekrarlar

• Başarının teyidi - herhangi bir 2xx; Sorduktan sonra hızlı ACK
• Подпись HMAC ('X-Signature: sha256 =...'), 'X-Webhook-Id', 'X-Retry'
• Retray politikası: backoff + jitter, 24-72 saate kadar
• DLQ + Replay: Kullanılabilir ve Doğrulanmış
• Alıcıda Dedup depolama, TTL ≥ retray pencereleri

9) Gözlemlenebilirlik ve izleme

• İstemci/SDK'da OpenTelemetry kancaları etkinleştirildi
• Zincir çapında trace _ id/X-Request-ID korelasyonu
• Дашборды: 'requests _ total', 'errors _ total {status}', 'latency _ p95', 'retry _ count', '429 _ rate'
• Alarmlar: 5xx/429 başak, p95 artış, başarı oranı düşüşü, webhook lag

promql rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

10) Performans ve istikrar

• Bağlantı havuzları, canlı tutun, mümkünse HTTP/2/3
• Backpressure, müşteri kuyruğu "şişirilmemiş"
• devre kesici/zaman aşımı/geri dönüş ilkeleri yapılandırıldı
• Yük testleri: patlama 10 ×, uzun bağlantılar, soğuk başlangıç

11) Veriler, para birimleri, zaman

• Formatlar: ISO-8601 UTC, para - ondalık dizeler/küçük birimler, yerel ortamlar çevreye bağlı değildir
• Kodlamalar/diller tutarlıdır (örn. Mesajlar için 'Accept-Language', makine için 'error _ code')
• Yuvarlama/komisyon politikası belgelendi

12) Uzlaşma

• checksums ile günlük/saatlik uzlaşma
• Test edilen mutabakatlar için API/yüklemeler (CSV/JSON, manifestolar/hashler)
• Tutarsızlıklar - 'trace _ id' referanslı biletlerde

13) Uyum ve yasal hususlar

• API Kullanım Şartları Kabul Edildi (adil kullanım/ihracat kontrolü)
• PII/Veri Sahipleri - Tanımlanan Roller ve Depolama Alanları
• Olaylar için Yasal Bekletme/Denetim Günlüğü Eylemleri Etkinleştirildi

14) Dokümantasyon ve Geliştirici Portalı

• OpenAPI/AsyncAPI alakalı, "kopyala-yapıştır" örnekleri var
• SDK (TS/Py/Java/Go/.NET) - sürümleri tutarlı, Cookbook mevcuttur
• Try-it oyun alanı çalışıyor, kum tuşları aktif
• Changelog/indirimler/yol haritası portalda görülebilir

15) Test: fonksiyonel, negatif, kaos

Fonksiyonel

• CRUD/anahtar senaryoları geçti (mutlu yol)
• Pagination/Cursor/Artımlı Deltalar

Negatif

• 401/403/404/409/422/429/5xx ve 'Retry-After' işleme
• Yanlış webhook imzası, süresi dolmuş belirteçler, büyük gövdeler

Kaos

• %10-30 olay bırakın, yeniden sıralayın, 1-10 dakika gecikmeler
• Bağımlılıkları devre dışı bırak (PSP/KYC) - doğru geri dönüş/hatalar

16) Kabul ve lansman (go-live)

• Nihai PRR (Üretim Hazırlık İnceleme) geçti
• Kanarya dahil: %10 - %25 - %50 - %100
• SLO sinyallerinde otomatik geri alma (hatalar/gecikme/429)
• Olay İletişim Matrisi ve Eskalasyon Yolu Yayınlandı
• Pilot oluşturulduktan sonra CAPA birikimi

17) Operasyon ve destek

• Runbook/playbooks: "5xx spike", "429 storm", "webhook backlog", "timeout"
• Düzenli SLO/Hata Bütçe Raporları
• Sırların ve tuşların bir programda döndürülmesi
• Versiyon Depresyonlar/Göçler Planı kabul edildi (gün batımı tarihi)

18) Eser desenleri

Env-yapılandırma şablonu

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: 256

Retray politikası (sözde)

json
{"initial":1,"max":60,"factor":2. 0,"jitter":0. 2,"retriable":["5xx","408","429"]}

19) Son kontrol listesi "imza için"

• Ortamlar/sürümler/anahtarlar/allowlist hazır
• Auth/JWT/keys/mTLS yapılandırılmış ve test edilmiş
• Sınırlar/kotalar/retrays/idempotency uygulanan
• Pagination/cursor/deltas veri üzerinde çalışır
• Webhooks: İmzalar, Tekrarlar, DLQ/Yeniden Oynatma Doğrulandı
• Errors 'problem + json', 'trace _ id' sticks to all logs
• Panolar/uyarılar toplandı, OTel etkin
• Yük/negatif/kaos testleri geçti
• Mutabakatlar ve raporlar birleşir, çalışma kitapları resmileştirilir
• PRR/canary/rollback-plan ready, on-call contacts ended

Toplam

Bu kontrol listesi, API entegrasyonunun teknik, operasyonel ve uyumluluk yönlerini kapsar. Öğeleri yukarıdan aşağıya doğru inceleyin, kontrol sınırlarını, idempotensi ve webhook'ları otomatikleştirin, gözlemlenebilirliği ve geri alma planını etkinleştirin - ve lansmanınız üretimde "sürprizler" olmadan öngörülebilir olacaktır.