API интеграциялоо тизмеси

0) Fast Review (ким эмне кылып жатат)

• Интеграциянын ээси дайындалды
• On-call байланыш (24 × 7/кул. саат) жазылган
• Макулдашылган SLO/SLA жана релиз колдоо терезе
• Статус-бет жана окуя канал (email/Slack/Webhook)

1) жеткиликтүүлүгү, айлана-чөйрө, версия

• Кирүү sandbox/staging/production алынды
• API версия тастыкталган: '/v1 '/аталышы 'X-API-Version'
• Allowlist IP жана тармак эрежелери орнотулган
• Саат жана TZ: UTC бардык убакыт, NTP синхрондоштуруу
• SemVer жана Matrix версиялары боюнча SDK/кардарлардын шайкештиги текшерилди

2) Аутентификация жана токендер

• Механизм макулдашылган: OAuth2 Client Credentials/Auth Code + PKCE/API Key/mTLS
• Access Token өмүрү жана Refresh Token өзгөртүү
• Үчүн API Key: сыр бир жолу көрсөтүлөт, жашыруун менеджер сакталат
• JWKS/JTI/' kid 'текшерилет, clock skew кирет ± 5 мин
• 'Authorization' аталыштары туура эмес (түзөтүү)

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

3) Коопсуздук жана купуялык

• TLS 1. 2 +/HSTS, кошумча mTLS
• PII-минималдаштыруу: Биз жөн гана керектүү жөнөтүү, ийбадатканаларда маска
• Сактоо жана алып салуу саясаты (GDPR/DSAR) документтештирилген
• Secret rotation: активдүү/кийинки ачкыч, rollover планы
• Каршы кыянаттык: Capcha/ачкычтарды түзүү ылдамдыгы/каттоо чектөөлөрү

4) Лимиттер, квоталар жана бэкофф

• Жарыяланган 'X-RateLimit- '/' X-Quota-' аталыштары
• Кардар 429 жана 'Retry-After' сыйлайт
• 5xx/408/429 үчүн гана Retrains, экспоненциалдуу backoff + jitter
• Берилген аракет/убакыт чеги (мисалы, ≤ 5 аракет, ≤ 60с жалпы)

5) Идемпотенттүүлүк жана чыр-чатактар

• Бардык write операциялары 'Idempotency-Key' менен жөнөтүлөт (TTL ≥ 24-72 саат)
• Дубликат чыр-чатак → 409 IDEMP_REPLAY иштетилет
• ETag/' If-Match 'атаандаштык жаңыртуулар үчүн киргизилген (бар болсо)

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

6) Пагинация жана инкременталдык дельта

• cursor/keyset pagination колдонулат ('next _ cursor', 'has _ more')
• Туруктуу сорттоо '(updated_at, id)' документтештирилген
• Инкременталдык түшүрүү: watermark же change token
• Жабуу терезелер (overlap 1-2 мин) жана дедуп '(id, version/seq)'

7) Ката форматы жана диагностика

• Бирдиктүү формат 'application/problem + json' (RFC 7807)
• Талааларды колдоо: 'error _ code', 'trace _ id', 'retriable', 'detail'
• Кардардын ката картасы жана иш-аракеттери сүрөттөлгөн (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) Вебхактар: квота жана кайталоо

• Ийгиликти ырастоо - ар кандай 2xx; enqueue кийин тез ACK
• Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Retray саясаты: backoff + jitter, чейин 24-72 саат
• DLQ + Replay: жеткиликтүү жана текшерилген
• ресивер боюнча депо-сактоо, TTL ≥ терезе retrais

9) Байкоо жана байкоо

• Кардар/SDK OpenTelemetry хаки киргизилген
• Корреляция 'trace _ id '/' X-Request-ID' бүт чынжыр боюнча
• Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
• Коңгуроо: 5xx/429, өсүш p95, күзүндө success rate, артта webhook

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

10) аткаруу жана туруктуулук

• Байланыш пулдары, keep-alive, HTTP/2/3 мүмкүн болгон жерде
• Параллелизм чектелген (backpressure), кардар кезек "көтөрүлүп" эмес,
• Circuit-breaker/timeout/fallback саясаты орнотулган
• Жүктөө тесттер: burst 10 ×, узун байланыш, муздак баштоо

11) Маалыматтар, валюталар, убакыт

• Форматтар: ISO-8601 UTC, акча - ондук саптар/кичинекей бирдиктер, жергиликтүү чөйрөгө көз каранды эмес
• Коддоолор/тилдер макулдашылган (мисалы, 'Accept-Language' билдирүүлөр үчүн, бирок 'error _ code' - машина)
• Тегеректөө/комиссия саясаты документтештирилген

12) Текшерүү жана отчеттуулук (reconciliation)

• контролдук суммалар менен күнүмдүк/саат салыштыруу
• текшерүү үчүн API/разгрузка (CSV/JSON, манифесттер/хэштер)
• Айырмачылыктар - 'trace _ id' шилтемелери менен билеттерге

13) Комплаенс жана укуктук аспектилери

• API колдонуу шарттары кабыл алынган (fair use/export control)
• PII/маалымат ээлери - ролдору жана сактоо зоналары аныкталган
• Legal Hold/аудит-журнал иш-аракеттер окуяларда киргизилген

14) Документация жана иштеп чыгуучулар порталы

• OpenAPI/AsyncAPI актуалдуу, мисалдар "көчүрүү-киргизүү" бар
• SDK (TS/Py/Java/Go/.NET) - макулдашылган нускалары, Cookbook жеткиликтүү
• Try-it playground иштейт, кум ачкычтары активдүү
• Changelog/депрекация/roadmap порталында көрүнүп турат

15) сыноо: функционалдык, терс, башаламандык

Функционалдык

• CRUD/негизги жагдайлар өттү (happy path)
• Пагинация/курсор/инкременталдык дельта

Терс

• 401/403/404/409/422/429/5xx жана иштетүү 'Retry-After'
• Туура эмес кол вебхук, мөөнөтү өтүп кеткен токендер, чоң денелер

Башаламандык

• Drop 10-30% окуялар, жазгыч, кечигүү 1-10 мин
• Көз карандылыкты өчүрүү (PSP/KYC) → туура fallback/каталар

16) Кабыл алуу жана ишке киргизүү (go-live)

• Акыркы PRR (Production Readiness Review) өттү
• Канар кошуу: 10% → 25% → 50% → 100%
• SLO сигналдар боюнча Auto артка (каталар/жашыруун/429)
• Байланыш окуя матрицасы жана эскалация жолу жарыяланды
• Бэклог CAPA кийин учкуч түзүлгөн

17) Иштетүү жана колдоо

• Runbook/playbook: "5xx spike", "429 storm", "webhook backlog", "timeout"
• SLO/Error Budget боюнча үзгүлтүксүз отчеттор
• Сырларды жана ачкычтарды график боюнча айлантуу
• Депрекация/миграция версияларынын планы макулдашылды (sunset датасы)

18) Артефакттардын үлгүлөрү

Env-конфига үлгүсү

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

Ретра саясаты (псевдо)

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

19) "Кол коюуга" жыйынтыктоочу чек-баракчасы

• Айлана-чөйрө/версиялары/ачкычтары/allowlist даяр
• Auth/JWT/keys/mTLS орнотулган жана сыналган
• Лимиттер/квоталар/retry/idempotentity ишке ашырылган
• Pagination/курсор/Delta маалыматтар боюнча иштейт
• Webhook: кол тамгалар, кайталоо, DLQ/Replay текшерилген
• 'problem + json', 'trace _ id' каталары бардык логинге жабышып калат
• Dashbord/Alert чогултулган, OTel киргизилген
• Жүктөө/терс/башаламандык-тесттер өттү
• Салыштыруу жана отчеттор бири-бирине дал келет, runbooks түзүлгөн
• PRR/канарейка/rollback планы даяр, байланыш on-call көрсөтүлгөн

Жыйынтык

Бул текшерүү тизмеси API интеграциясынын техникалык, операциялык жана комплаенс аспектилерин жабат. Жогорудан ылдый пункттарды басып өтүңүз, лимиттерди, демпотенттикти жана вебхуктарды текшерүүнү автоматташтырыңыз, байкоону жана артка кайтаруу планын күйгүзүңүз - жана сиздин ишке киргизүү алдын ала болот, өндүрүштө "сюрпризсиз".