Ishga tushirishda beshta muhim API integratsiyalashuvi xatosi

Xato № 1. Idempotentlik va retray «bo’roni» yo’q

Alomatlar: buyurtmalar/to’lovlar dubli, summalar tafovuti, bahsli qaytarmalar, DLQ alertlari o’sib bormoqda.

Ildizi: soʻrovlar/vebxuklarni qayta yetkazib berish va tarmoq flappisi - normal. Agar «yaratish/hisobdan chiqarish» operatsiyasi idempotent bo’lmasa, retralar zararni ko’paytiradi.

Qanday qilib to’g’ri

Idempotency-Key/’ operation _ id’barcha xavfli usullarga (POST/PATCH).

«operation _ id» DBdagi noyob indeks. Takrorlash - oxirgi natijani qaytaring.

Vebxuklar Inbox jadvali orqali (dedupe’event _ id + signature’). Chiqish hodisalari - Outbox.

Retralar: ko’pi bilan 1-2 marta, eksponent + jitter, faqat xavfsiz operatsiyalar uchun.

HTTP-konvensiya (misol):

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

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

SQL himoyasi (soddalashtirilgan):

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

Jitter bilan retray (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

Chek varaqasi:

Barcha «pul/yaratuvchi» mantiq’operation _ id’va unik-indeksga ega.
Kirish vebxuklari faqat idempotent vorkeri bilan Inbox orqali.
Mijoz SDK avtomatik ravishda Idempotency-Key belgisini qo’yadi.

Xato № 2. Taym-autlar/SLOga qarshi retrajlar: qaramlikning «haddan tashqari qizib ketishi»

Alomatlar: p95 to’satdan suzib ketadi, navbatlar ko’payadi, circuit breaker «chayqaladi».

Ildizi: javobning umumiy SLO - 400-600 ms, tashqi APIga taym-autlar - 1-2 s va yana retralar × 3. Siz qo’lingizdan kelgancha ko’proq ish qilasiz va qaramlikni takrorlash orqali bostirib kirasiz.

Qanday qilib to’g’ri

Budget-tayming: agar SLO 400 ms, upstream-taym-aut: 250-300 ms; so’rovning umumiy taym-aut ≤ SLO.

Limits/Backpressure: semaforlar/worker-pool har bir qaramlik uchun chaqiruvlarga. Birdaniga to’lib toshgan → 429/503.

Circuit breaker:’open’taym-autlarda/5xx,’half-open’dozalangan.

Admission control: parallellikni cheklash.

Misol (Go):

go sem: = make (chan struct {}, 64 )//raqobat limiti 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//cheksiz navbat o’rniga darhol rad etish
}
}

Chek varaqasi:

Vaqt-autlar SLOdan qisqaroq; ≤ 2 retrasi; Jitter bor.
Tashqi API uchun pullar/semaforlar; metrlar bilan circuit breaker.
«busy» yo’nalishlarida ulanishlarni ushlab turish o’rniga 429/Retry-After qaytaramiz.

Xato № 3. Zaif xavfsizlik: vebxuk imzolari, sirlar, TLS

Alomatlar: «begona» vebxuklar o’tadi, koddagi/logdagi sirlar, MITM xavflari.

Ildizi: imzo/yangilik tekshirilmaydi, sirlar env fayllarda, eski TLS va zaif sarlavhalarda yashaydi.

Qanday qilib to’g’ri

Vebxuklarning imzosi HMAC-SHA256 +’X-Timestamp’(oyna ≤ 5-10 daqiqa), imzoni qat’iy taqqoslash.

tanqidiy integratsiyalar uchun mTLS yoki IP allow-list.

Maxfiylarni Vault/Cloud KMS orqali almashtirish; huquqlar minimumi; chegirma auditi.

TLS 1. 2/1. 3 only, HSTS, toʻgʻri CORS (manbalarning tor roʻyxati).

Imzoni tekshirish (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()

Chek varaqasi:

Barcha vebxuklar imzolangan va tekshirilmoqda; oynasi cheklangan.
KMS/Vault sirlari, rotatsiya va audit mavjud.
TLS/HSTS kiritilgan; CORS nuqtali; Mos IP/mTLS.

Xato № 4. Kontrakt-drift: «o’z hayotini yashadi» sxemasi

Simptomlari: «faqat ba’zi mijozlarda», 500/422 log, SDK va APIning turli versiyalari bahslashmoqda.

Ildizi: kontraktlarning qat’iy tavsifi yo’q, teskari mos kelmaydigan o’zgarishlar, «sokin» maydonlar, bir xil nomlarning ma’nosi turlicha.

Qanday qilib to’g’ri

Birinchi shartnoma: OpenAPI/AsyncAPI + serverlar/mijozlar ishlab chiqarish; voqealar uchun - Euro/Protobuf + Schema Registry.

Version:’v1 → v2’(URI/xeder), deprecation-plan, grace-davr.

Backward-compat: faqat minor relizlardagi additive oʻzgarishlar; v-bumpsiz olib tashlash/qayta nomlash taqiqlanadi.

Shartnoma testlari: Pact/Buf - provayder/konsumer CI da tekshiriladi.

Misollar:

yaml
OpenAPI: kichik birliklardagi aniq amount_minor turi:
type: integer minimum: 0 description: Minimal valyuta birliklaridagi summa (butun)

Chek varaqasi:

Kontraktlar git da saqlanadi, CI mos kelmasa validatsiya qiladi/buzadi.
Voqealar uchun sxemalar registrlari, «back/forward» mosligi.
O’zgarishlar sahifasi, deprikatsiya sanasi, sheriklar uchun test stendi.

Xato № 5. «Ko’r» ishga tushirish: metrik/loglar/treyslar va qum qutisi yo’q

Alomatlar: «hech narsa ko’rinmaydi», qo’llab-quvvatlashga to’la, debag - qo’llar bilan.

Ildizi: ko’rinish yo’q, sintetika yo’q, qum qutisi «so’z bilan» sinovdan o’tkazildi.

Qanday qilib to’g’ri

RED/USE-metriklar: rate/error/latency har bir endpoint, yo’nalishlar/usullar bo’yicha.

Korrelyatsiya:’trace _ id’barcha loglar va javoblarda; so’rovni bog’lab qo’ydi.

Sintetika: health-problar (login/deposit-qum), vebxuklar uchun SLA-monitoring T + 60.

Qum qutisi/steyj: toʻliq izolyatsiya qilingan kalitlar/domenlar, soxta PSP, yozuvlar «hisobotlarga kiritilmaydi».

Trace ID bilan javob:

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

Chek varaqasi:

RED/USE metrikalari, dashbordlar, alertlar (alomatlar + sabablar).
Treyslar end-to-end; JSON loglari, PIIsiz,’trace _ id’.
Asosiy mintaqalardan sintetika; Albatta, qum qutisi, turli kalitlar.

Prelaunch rejasi (T-7 → T-0)

T-7 kun:

Yakuniy kontrakt-skan: mos kelmaydigan o’zgarishlar yo’qmi; freeze sxemalari.
Sirlar/sertifikatlar: rotatsiya, kirish, KMS siyosatini tekshiring.
Sintetika 24 × 7, alertlar on-call bilan bog’langan.

T-3 kun:

Yuk mini-yugurish (burst 2-5 daqiqa): r95/pula/yashil zonadagi navbatlar.
DRY-RUN vebxuk (takrorlash, 5xx, jitter), DLQ tekshiruvi.
Hamkorlarning «Telefon kitobi»: L1/L2 aloqalar, war-room kanali.

T-0:

SLO-geytlar bo’yicha 5% → 25% → 50% kanareysh trafigi; rollback tayyor.
Xavfli fichlarda kill-switch/feature-flags yoqilgan.
War-room aktiv, maqom namunalari tayyorlangan.

Rollbek-reja (agar biror narsa noto’g "ri bo’lsa)

1. Trafikni oldingi barqaror versiya/yoʻnalishga olib tashlash.

2. Munozarali oʻzgarishlarni ficheflagdan oʻchirish.

3. Navbat/hovuzlarni barqarorlashtirish, «bo’ron» paytida retrajlarni to’xtatish.

4. Post-hodisa: taymline, ildiz, vazifalarni yig’ish (fix-forvard/kontrakt fixlari).

Ishga tushirish uchun o’zini o’zi tekshirish jadvali (qisqa)

Blok	Savol	Ha/Yoʻq
Idempotentlik	Barcha «yaratuvchi» usullarda Idempotency-Key/’ operation _ id’va unik-indeks bormi?
Retray/taym-autlar	Vaqt-autlar SLOdan qisqaroq; ≤ 2 retrasi; Jitter yoqilganmi?
Xavfsizlik	Vebxuklar imzolangan, yangilik oynasi ≤ 10 daqiqa, KMS sirlari?
Kontraktlar	OpenAPI/AsyncAPI oʻrnatilganmi?
Kuzatish	RED/USE, treyslar, sintetika T + 60, qum qutisi izolyatsiya qilinganmi?
Rollback	Qaytish/kill-switch tugmasi, aloqa rejasi bormi?

Ko’pincha «Nima qilish kerak, agar...»

... provayder Idempotency-Key dasturini qoʻllab-quvvatlamayaptimi?

’hash (body)’ +’partner _ request _ id’ni saqlang va idempotentligingizni kiriting.

... vebxuklar ba’zan javobdan oldin keladimi?

’operation _ id’ bilan tiking va vaqtincha «unknown → reconcile» maqomini saqlang; davriy reconciler tafovutlarni yopadi.

... eski mijozlar va yangi mijozlarni qo’llab-quvvatlash kerakmi?

Endpoint’larni (’/v1’va ’/v2’) versiya qiling, sarlavha/URI bo’yicha yo’naltiring, kamida N oy davomida backward mosligini saqlang.

Xulosa

Integratsiya muvaffaqiyatsizliklari deyarli har doim bir xil narsaga bog’liq: idempotentlik yo’q, noto’g’ri taym-autlar va retrajlar, vebxuklarning zaif imzosi, kontraktlarning dreyfi va ko’rinishning yo’qligi. Shartnomalarni oldindan tuzing, kuzatishni yoqing, chegaralarni/bekpresherni belgilang, barcha tashqi aloqalarni imzolang va sintetikani ishga tushiring. Shunda, hatto sheriklar muvaffaqiyatsizlikka uchragan taqdirda ham, sizning relizingiz boshqariladi - retrada yo’qolgan pulsiz va butun jamoada uyqusiz tunsiz.