Başlanğıc zamanı beş kritik API inteqrasiya səhvləri

Səhv № 1. Heç bir idempotentlik və «fırtına» retrains

Simptomlar: sifarişlərin/ödənişlərin dublları, məbləğlərin uyğunsuzluğu, mübahisəli geri qaytarmalar, DLQ riskləri artır.

Kök: sorğuların/vebhukların yenidən çatdırılması və şəbəkə flappi normaldır. Yarat/silmə əməliyyatı idempotent deyilsə, retralar ziyanı artırır.

Necə düzgün

Idempotency-Key/' operation _ id 'bütün təhlükəli metodlara (POST/PATCH).

DB-də unikal indeks 'operation _ id'. Təkrar - son nəticəni qaytarın.

Inbox cədvəli vasitəsilə webhucks (dedupe 'event _ id + signature'). Çıxış hadisələri - Outbox.

Retray: maksimum 1-2 dəfə, eksponent + jitter, yalnız təhlükəsiz əməliyyatlar üçün.

HTTP konvensiyası (nümunə):

http
POST /v1/payments
Idempotency-Key: ik_f35a2
Content-Type: application/json

{"amount": 5000, "currency": "EUR", "source": "card_..."}

SQL-qorunması (sadələşdirilmiş):

sql
ALTER TABLE payments ADD CONSTRAINT uniq_op UNIQUE (operation_id);

Jitterlə retraylar (psevdokod):

python for i in range(2):
try: return call_api(payload, timeout=0. 6)
except Timeout:
sleep(0. 05 2i + random. uniform(0, 0. 05))
raise UpstreamUnavailable

Çek siyahısı:

Bütün «pul/yaradıcı» məntiqin 'operation _ id' və uniq-indeksi var.
Gələn webhucks yalnız idempotent worker ilə Inbox vasitəsilə.
Müştəri SDK avtomatik olaraq Idempotency-Key-i təyin edir.

Səhv № 2. Zaman aşımı/SLO-ya qarşı retralar: asılılığın «həddindən artıq qızması»

Simptomlar: p95 qəfildən üzür, növbələr artır, circuit breaker «çırpır».

Kök: cavabın ümumi SLO - 400-600 ms, xarici API-yə time-autlar - 1-2 s, hətta retralar × 3. Siz bacardığınızdan daha çox iş görürsünüz və asılılığı təkrarlayırsınız.

Necə düzgün

Budget-time: SLO 400 ms, upstream-time-off: 250-300 ms; SLO ≤ ümumi zaman aşımı sorğusu.

Limits/Backpressure: semafors/worker-pool hər asılılıq çağırışlar. dolu → 429/503 dərhal.

Circuit breaker: time-auts/5xx-də 'open', 'half-open' dozası.

Admission control: paralelliyi məhdudlaşdırın (axın, endpoint/PSP).

Nümunə (Go):

go sem: = make (chan struct {}, 64 )//PSP func callPSP (ctx context. Context, req Req) (Res, error) {
select {
case sem <- struct{}{}:
defer func(){ <-sem }()
c, cancel:= context. WithTimeout(ctx, 300time. Millisecond)
defer cancel()
return psp. Do(c, req)
default:
return Res {}, ErrBusy//sonsuz növbə əvəzinə dərhal imtina
}
}

Çek siyahısı:

SLO-dan daha qısa vaxt; retralar ≤ 2; Jitter var.
Xarici API-lərdə hovuzlar/semaforlar; metrlər ilə circuit breaker.
«busy» marşrutlarında 429/Retry-After qaytarırıq, bağlantıları saxlamırıq.

Səhv № 3. Zəif təhlükəsizlik: vebhuk imzaları, sirləri, TLS

Simptomlar: «yad» webhucks kod/log, MITM-riskləri gizli keçir.

Kök: heç bir imza/təravət yoxlama, sirləri env fayllarda yaşayır, köhnə TLS və zəif başlıqlar.

Necə düzgün

Webhook imzası HMAC-SHA256 + 'X-Timestamp' (pəncərə ≤ 5-10 dəq), ciddi imza müqayisə.

kritik inteqrasiya və ya IP allow-list üçün mTLS.

Vault/Cloud KMS vasitəsilə sirləri çevirmək; minimum hüquqlar; endirim auditi.

TLS 1. 2/1. 3 only, HSTS, doğru CORS (dar mənbələr siyahısı).

İmza yoxlaması (Python):

python def verify(sig_hdr, ts_hdr, body, secret):
if abs(time. time() - int(ts_hdr)) > 600: raise Expired()
calc = hmac. new(secret, (ts_hdr + "." + body). encode(), hashlib. sha256). hexdigest()
if not hmac. compare_digest(calc, sig_hdr): raise BadSig()

Çek siyahısı:

Bütün webhucks imzalanır və yoxlanılır; təzəlik pəncərə məhduddur.
KMS/Vault sirləri, rotasiya və audit var.
TLS/HSTS daxildir; CORS nöqtə; Uyğun olduğu yerdə IP/mTLS.

Səhv № 4. Müqavilə-drift: «Öz həyatını yaşadı» sxemi

Simptomlar: Prod düşmüş «yalnız müştərilərin bir hissəsi», 500/422 log, SDK və API müxtəlif versiyaları mübahisə.

Kök: müqavilələrin ciddi təsviri yoxdur, əks uyğun olmayan dəyişikliklər, «sakit» sahələr, eyni adların fərqli mənaları.

Necə düzgün

Birinci müqavilə: OpenAPI/AsyncAPI + server/müştəri istehsalı; hadisələr üçün - Avro/Protobuf + Schema Registry.

Versiyası: 'v1 → v2' (URI/heder), deprecation-plan, grace-period.

Backward-compat: minor buraxılışlarda yalnız additive dəyişikliklər; v-bump olmadan silmək/yenidən adlandırmaq qadağasıdır.

Müqavilə testləri: Pact/Buf - provayder/konsumer CI-də yoxlanılır.

Nümunələr:

yaml
OpenAPI: minor vahidlərdəki dəqiq amount_minor növü:
type: integer minimum: 0 description: Minimum valyuta vahidlərindəki məbləğ (tam)

Çek siyahısı:

Müqavilələr git-də saxlanılır, CI uyğunsuzluq zamanı validasiya/pozulur.
Hadisələr üçün sxem qeydləri, uyğunluq «back/forward».
Dock-səhifə dəyişikliklər, deprikasiya tarixləri, tərəfdaşlar üçün test standı.

Səhv № 5. «Kor» başlanğıc: heç bir metrik/yuva/treys və qum qutusu

Simptomlar: «heç nə görünmür», dəstək, debaq - protoda əllər.

Kök: müşahidə edilmir, sintetika yoxdur, qum qutusu «sözlə» sınanır.

Necə düzgün

RED/USE metrikası: rate/error/latency hər endpoint, marşrutlar/metodlar üzrə.

Korrelyasiya: 'trace _ id' bütün log və cavablarda; Bir dəstə sorğu webhuk.

Sintetik: sağlamlıq testləri (login/deposit-qum), SLA monitorinq T + 60 vebhuk üçün.

Qum qutusu/steyj: tamamilə təcrid olunmuş açarlar/domenlər, uydurma PSP, qeydlər «hesabatlara daxil deyil».

Trace ID ilə cavab:

http
HTTP/1. 1 202 Accepted
Trace-Id: 7f2b3d8e9c1a4
Location: /v1/ops/req_42/status

Çek siyahısı:

RED/USE metrikləri, daşbordlar, alertlər (simptomlar + səbəblər).
End-to-end Traces; JSON log, PII olmadan, 'trace _ id'.
Əsas bölgələrdən sintetika; qum qutusu məcburidir, açarlar fərqlidir.

Prelaunch planı (T-7 → T-0)

T-7 gün:

Final kontrakt-scan: uyğun olmayan dəyişikliklər var; freeze sxemləri.
Secrets/sertifikatlar: rotasiya, giriş, KMS siyasətlərini yoxlayın.
Sintetik 24 × 7, alertlər on-call ilə bağlıdır.

T-3 gün:

Yük mini-qaçış (burst 2-5 dəq): p95/hovuzlar/yaşıl zonada növbələr.
DRY-RUN vebhuk (repeats, 5xx, jitter), DLQ yoxlama.
Partnyorların «Telefon kitabı»: L1/L2 əlaqə, war-room kanalı.

T-0:

5% → 25% → 50% SLO geytləri ilə kanar trafik; hazır rollback.
Riskli fiqurlarda kill-switch/feature-flags daxildir.
War-room aktiv, status şablonları hazırlanmışdır.

Rollback planı (bir şey səhv olarsa)

1. Əvvəlki sabit versiya/marşrut üçün trafik çıxarın.

2. Mübahisəli dəyişiklikləri ficheflagla söndürün.

3. Növbələri/hovuzları sabitləşdirin, «fırtına» zamanı retrayları dayandırın.

4. Post-insident: time line, kökləri, vəzifələri (fiks-forvard/müqavilə fiksləri) toplamaq.

Başlanğıc üçün özünü yoxlama cədvəli (qısa)

Blok	Sual	Bəli/Yox
İdempotentlik	Bütün «yaradan» metodların Idempotency-Key/' operation _ id 'və uniq-indeksi varmı?
Retrai/Time-auts	SLO-dan daha qısa vaxt; retralar ≤ 2; Jitter aktiv?
Təhlükəsizlik	Webhucks imzalanmış, təzəlik pəncərə ≤ 10 min, KMS sirləri?
Müqavilələr	OpenAPI/AsyncAPI sabit, CI tutur uyğunsuzluq?
Müşahidə	RED/USE, treys, sintetik T + 60, qum qutusu təcrid?
Rollbek	Geri qaytarma/kill-switch düyməsi, rabitə planı varmı?

Tez-tez verilən «bəs əgər...»

... provayder Idempotency-Key dəstəkləmir?

'hash (body)' + 'partner _ request _ id' saxlayın və idempotentliyinizi daxil edin.

... vebhuk bəzən «əvvəl» cavab gəlir?

'operation _ id' ilə tikin və müvəqqəti olaraq «unknown → reconcile» statusunu saxlayın; periodik reconciler uyğunsuzluqları bağlayacaq.

... köhnə müştərilərə və yeni müştərilərə dəstək olmaq lazımdır?

Endpoint '('/v1' və '/v2 ') versiyası, başlıq/URI marşrutu, minimum N ay backward uyğunluğu saxlayın.

Xülasə

İnteqrasiya uğursuzluqları demək olar ki, həmişə eyni şeydir: heç bir idempotentlik, səhv vaxt və retralar, zəif veb-hook imzası, müqavilələrin sürüklənməsi və görünürlük olmaması. Əvvəlcədən müqavilələri düzəldin, müşahidə qabiliyyətini açın, limitləri/backpresher qoyun, bütün xarici qarşılıqlı əlaqələri imzalayın və sintetikanı işə salın. Belə ki, partnyorlarınızın uğursuzluqları olsa belə, buraxılışınız idarə edilə bilər - retralarda itirilmiş pul olmadan və bütün komanda üçün yuxusuz gecə olmadan.