Рӯйхати санҷиши ҳамгироии API

0) Шарҳи зуд (кӣ кор мекунад)

• Соҳиби ҳамгироӣ таъин шудааст
• Тамосҳои занг (24 × 7/соати корӣ) таъин карда мешаванд
• SLO/SLA-и мувофиқашуда ва равзанаи дастгирии озодкунӣ
• Саҳифаи вазъ ва канали ҳодиса (почтаи электронӣ/slack/webhook)

1) Дастрасӣ, муҳит, версияҳо

• қуттии қуттӣ/саҳна/истеҳсолот дастрас аст
• Версияи API тасдиқ кард: '/v1 '/сарлавҳа 'X-API-Version'
• Иҷозат додани қоидаҳои IP ва шабака
• Соат ва TZ: ҳама вақт дар UTC, ҳамоҳангсозии NTP
• Мутобиқати муштарӣ ва матритсаи версия тасдиқ карда шуд

2) Аутентификатсия ва нишонаҳо

• Механизм мувофиқа карда шуд OAuth2 Эътимодномаи муштариён/Кодекси Auth + PKCE/API Key/MTLS
• Мӯҳлати дастрасии токен ва навсозии гардиши токен танзим карда шудааст
• Барои калиди API: махфӣ як маротиба нишон дода мешавад, дар менеҷери махфӣ нигоҳ дошта мешавад
• JWKS/JTI/' кӯдак 'тафтиш карда шуд, соати корӣ дар ± 5 дақиқа
• 'Авторизатсия' сарлавҳаҳо сабт нашудаанд (таҷдиди назар)

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

3) Амният ва махфият

• TLS 1. 2 +/HSTS, ихтиёрии m-TLS
• Кам кардани PII: мо танҳо чизҳои заруриро мефиристем, ниқобҳо дар гузоришҳо
• Сиёсати нигоҳдорӣ ва ихтиёрдорӣ (GDPR/DSAR) ҳуҷҷатгузорӣ шудааст
• Гардиши махфӣ: калиди фаъол/навбатӣ, нақшаи гардиш
• Зидди сӯиистифода: Маҳдудиятҳои суръат/сабти Captcha/Keying

4) Маҳдудиятҳо, квотаҳо ва бозгашт

• Сарлавҳаҳои 'X-Rate' Limit- '/' X-Quota- 'эълон карда шуданд
• Мизоҷон 429 ва 'Retry-After' -ро эҳтиром мекунанд
• Танҳо барои 5xx/408/429, пушти экспоненсиалӣ + ҷиттер
• Вақти такрорӣ/мӯҳлат (масалан 5 такрорӣ, ҳамагӣ 60c)

5) Идемпотентсия ва низоъҳо

• Ҳама амалиётҳои навиштан бо 'Idempotency-Key' (TTL ≥ 24-72 h) фиристода мешаванд
• Ихтилофи такрорӣ → 409 IDEMP_REPLAY Дастӣ
• ET/ag/' If-Match 'барои навсозиҳои рақобат фаъол аст (агар дастрас бошад)

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

6) Пагинатсия ва дельтҳои афзоянда

• курсор/пагинатсияи тугмаи истифодашуда ('next _ cursor', 'has _ more')
• Навъи устувор '(updated_at, id)' ҳуҷҷатгузорӣ шудааст
• Боркуниҳои афзоянда: нишонаи об ё аломати тағирот
• Такрори (такрори 1-2 дақиқа) ва тарҳ аз ҷониби '(id, version/seq)'

7) Формат ва ташхиси хатогӣ

• Формати ягонаи 'барнома/мушкилот + json' (RFC 7807)
• Дастгирии саҳроӣ: 'хатогӣ _ код', 'trace _ id', 'retriable', 'муфассал'
• Харитаи хатогӣ ва амалҳои муштарии тавсифшуда (дафтарчаи иҷро)

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: эътироф ва такрори

• Тасдиқи муваффақият - ҳар гуна 2xx; ACK зуд пас аз дархост
• Подпись HMAC ('Имзои X: sha256 =...'), 'X-Webhook-Id', 'X-Retry'
• Сиёсати бозгашт: backoff + jitter, то 24-72 соат
• DLQ + Такрори: Дастрас ва тасдиқшуда
• Нигоҳдории Dedup дар қабулкунанда, TTL ≥ бозгардонидани тирезаҳо

9) Мушоҳида ва пайгирӣ

• Қалмоқҳои кушодаи Telemetry дар муштарӣ/SDK фаъол карда шудаанд
• Таносуби васеъи занҷир _ id/X-Request-ID
• Душборды: 'дархостҳо _ ҳамагӣ', 'хатогиҳо _ total {status}', 'latency _ p95', 'retry _ count', '429 _ rate'
• Ҳушдорҳо: 5xx/429 хӯша, болоравии p95, паст шудани сатҳи муваффақият, ақибмонии webhook

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

10) Иҷро ва субот

• Ҳавзҳои пайвастшавӣ, зинда мондан, HTTP/2/3 ҷое ки имконпазир аст
• Backpressure, навбати муштарӣ "афтида" нест
• сиёсати схема/танаффус/бознишастагӣ танзим карда шудааст
• Санҷишҳои сарборӣ: дарида шудани 10 ×, пайвастҳои дароз, оғози хунук

11) Маълумот, асъор, вақт

• Форматҳо: ISO-8601 UTC, сатрҳои пулӣ/воҳидҳои хурд, маҳалҳо аз муҳит вобаста нестанд
• Рамзгузорӣ/забонҳо пайваста мебошанд (масалан, 'Қабул кардани забон' барои паёмҳо, аммо 'хатогӣ _ код' барои мошин)
• Яклухткунӣ/сиёсати комиссия ҳуҷҷатгузорӣ шудааст

12) Оштӣ

• Мусолиҳаи ҳаррӯза/ҳарсоата бо чекҳо
• API/боргузорӣ барои мусолиҳаи санҷидашуда (CSV/JSON, зуҳурот/hashes)
• Ихтилофҳо - дар чиптаҳо бо истинод ба 'trace _ id'

13) Мувофиқат ва ҷанбаҳои ҳуқуқӣ

• Шартҳои истифодаи API (истифодаи одилона/назорати содирот)
• Дорандагони PII/Маълумот - Нақшҳо ва минтақаҳои нигоҳдорӣ муайян карда шуданд
• Амалҳои сабти қонунӣ/аудит барои ҳодисаҳо фаъол карда шудаанд

14) Портали ҳуҷҷатгузорӣ ва таҳиякунанда

• Open
• SDK (TS/Py/Java/Go/.NET) - версияҳо мувофиқанд, Китобча дастрас аст
• Корҳои майдончаи бозӣ, калидҳои қум фаъоланд
• Changelog/коҳиш/харитаи роҳ дар портал намоён аст

15) Санҷиш: функсионалӣ, манфӣ, бетартибӣ

Функсионалӣ

• Сенарияҳои CRUD/калидӣ гузаштанд (роҳи хушбахтона)
• Пагинатсия/Курсор/Deltas афзоиш

Манфӣ

• 401/403/404/409/422/429/5xx ва коркарди 'Retry-After'
• Имзои нодурусти webhook, нишонаҳои мӯҳлати истифодашуда, баданҳои калон

бетартибӣ

• Рӯйдодҳои 10-30% -ро партоед, фармоиш диҳед, 1-10 дақиқа ба таъхир афтад
• Вобастагиро хомӯш кунед (PSP/KYC) → хатогиҳои дуруст/хатогиҳо

16) Қабул ва роҳандозӣ (зинда)

• PRR ниҳоӣ (Шарҳи омодагии истеҳсолӣ) гузашт
• Фарогирии канарӣ: 10% → 25% → 50% → 100%
• Бозгашти худкор дар сигналҳои SLO (хатогиҳо/ниҳонӣ/429)
• Матритсаи тамос бо ҳодисаҳо ва роҳи афзоиш нашр шудааст
• Қафои CAPA пас аз тавлиди пилот

17) Амалиёт ва дастгирӣ

• Китобчаҳо/дафтарҳои бозӣ: "5xx хӯша", "429 тӯфон", "пушти webhook", "танаффус"
• Ҳисоботи мунтазами SLO/Хатогӣ дар бораи буҷа
• Гардиши асрори калидҳо ва калидҳо аз рӯи ҷадвал
• Нақшаи депрессия/муҳоҷират розӣ шуд (санаи ғуруби офтоб)

18) Намунаҳои артифакт

Қолаби Env-config

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) Рӯйхати ниҳоии "барои имзо"

• Муҳитҳо/версияҳо/калидҳо/рӯйхати аллюстҳо омодаанд
• Auth/JWT/тугмаҳо/MTLS танзим ва озмуда шудаанд
• Маҳдудиятҳо/квотаҳо/пардохтҳо/idempotency татбиқ карда мешаванд
• Пагинатсия/курсор/дельтҳо дар маълумот кор мекунанд
• Webhooks: Имзоҳо, Бозсозӣ, DLQ/Такрори тасдиқшуда
• Мушкилоти хатогиҳо + json ',' пайгирӣ _ id 'ба ҳама гузоришҳо
• Панели панелҳо/огоҳиҳои ҷамъоваришуда, OT bel фаъол аст
• Санҷишҳои сарборӣ/манфӣ/бетартибӣ гузаштанд
• Ҳамоҳангсозӣ ва ҳисоботҳо муттаҳид мешаванд, дафтарчаҳо ба расмият дароварда мешаванд
• PRR/канарӣ/нақшаи бозгашт, тамосҳои занг нишон дода шудаанд

Ҷамъ

Ин рӯйхати назоратӣ ҷанбаҳои техникӣ, амалиётӣ ва мутобиқати ҳамгироии API-ро фаро мегирад. Аз ашёҳо аз боло ба поён гузаред, маҳдудиятҳои санҷиш, idempotency ва webhooks автоматӣ кунед, мушоҳида ва нақшаи бозгаштро фароҳам оваред - ва оғози шумо бидуни "ногаҳонӣ" дар истеҳсолот пешбинӣ мешавад.