API ინტეგრაციის Checlist

0) სწრაფი მიმოხილვა (ვინ აკეთებს)

დაინიშნა ინტეგრაციის მფლობელი

კონტაქტები on-call (24 × 7/მონა). საათი) ასახულია
თანხმოვანი SLO/SLA და გამოშვების დამხმარე ფანჯარა
სტატუსის გვერდი და ინციდენტების არხი (email/Slack/Webhook)

1) წვდომა, გარემო, ვერსიები

წვდომა sandbox/staging/production მიღებულია
API ვერსია დადასტურებულია: '/v1 '/სათაური 'X-API-Version "
Allowlist IP და ქსელის წესები
საათი და TZ: ყველა დრო UTC, NTP სინქრონიზაცია
SDK/კლიენტების თავსებადობა SemVer- ის და ვერსიის მატრიცის მიხედვით

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) დოკუმენტირებულია
საიდუმლო როტაცია: აქტიური/შემდეგი გასაღები, როლოვერის გეგმა
Anti Abuse: Capcha/რეგისტრაციის გასაღების შექმნის/შეზღუდვის სიჩქარე

4) ლიმიტები, კვოტები და ბეკოფი

გამოცხადდა 'X-RateLimit- '/' X-Éta-' სათაურები
კლიენტი პატივს სცემს 429 და 'Retry-After'
Retrai მხოლოდ 5xx/408/429, ექსპონენციალური backoff + jitter
დადგენილია მცდელობების/დროის ზღვარი (მაგალითად, 5 მცდელობა, მთლიანობაში 60s)

5) Idempotence და კონფლიქტები

ყველა 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 პაგინაცია ('შემდეგი _ cursor', 'has _ more')
სტაბილური დალაგება '(განახლებულია _ at, id)' დოკუმენტირებულია
საგანგებო გადმოტვირთვა: watermark ან change token
გადახურვის ფანჯრები (overlap 1-2 წუთი) და დედაპაპი '(id, version/seq)'

7) შეცდომები და დიაგნოზი

ერთიანი პროგრამა 'განაცხადი/problem + json "(RFC 7807)
ველების მხარდაჭერა: 'error _ code', 'trace _ id', 'retrable', '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; სწრაფი ACK enqueue
Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
ხელახალი პოლიტიკა: backoff + jitter, 24-72 საათამდე
DLQ + Replay: ხელმისაწვდომი და გადამოწმებული
თოვლის ბაბუა მიმღების მახლობლად, TTL - Retray ფანჯრები

9) დაკვირვება და ტრეკირება

OpenTelemetry huks შედის კლიენტში/SDK
კორელაცია 'trace _ id '/' X-Request-ID' მთელ ჯაჭვში
Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
Alarms: ზრდა 5xx/429, ზრდა p95, success rate, webhuk lag

PromQL (მაგალითი):

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

10) პროდუქტიულობა და სტაბილურობა

ნაერთების აუზები, keep-alive, HTTP/2/3 სადაც შესაძლებელია
პარალელიზმი შეზღუდულია, კლიენტის ჯერი არ „იშლება“
პოლიტიკოსები circuit-breaker/timeout/fallback
დატვირთვის ტესტები: burst 10 ×, გრძელი ნაერთები, ცივი დასაწყისი

11) მონაცემები, ვალუტა, დრო

ფორმატები: ISO-8601 UTC, ფული - ათობითი ხაზები/მინი ერთეულები, იდაყვის არ არის დამოკიდებული გარემოზე
კოდირება/ენები შეთანხმებულია (მაგალითად, 'Accept-Language' შეტყობინებებისთვის, მაგრამ 'error _ code' არის მანქანა)
დამრგვალების/კომისიების პოლიტიკა დოკუმენტირებულია

12) Conconciliation

ყოველდღიური/საათის კრეკერები საკონტროლო თანხებით
API/მოხსნისთვის ტესტირება (CSV/JSON, მანიფესტები/ჰეში)
შეუსაბამობები - თიკეტებში მითითებით „trace _ id“

13) შესაბამისობა და სამართლებრივი ასპექტები

API- ს გამოყენების პირობები მიღებულია
PII/მონაცემთა მფლობელები - განისაზღვრება როლები და შენახვის ადგილები
იურიდიული ჰოლდი/ქმედებების აუდიტის ლოგო შედის ინციდენტებში

14) დოკუმენტაცია და განვითარების პორტალი

OpenAPI/AsyncAPI აქტუალურია, არსებობს „კოპირების ჩასმის“ მაგალითები
SDK (TS/Py/Java/Go/.NET) - შეთანხმებულია ვერსიები, Cookbook ხელმისაწვდომია
Try-it playground მუშაობს, ქვიშის გასაღებები აქტიურია
Changelog/დეპრესიები/roadmap ჩანს პორტალში

15) ტესტირება: ფუნქციური, უარყოფითი, ქაოსი

ფუნქციური

CRUD/საკვანძო სცენარები დასრულებულია (ბედნიერი პატი)
პაგინაცია/კურსორი/საგანგებო დელტა

უარყოფითი

401/403/404/409/422/429/5xx და დამუშავება 'Retry-After'
ვებჰუკის არასწორი ხელმოწერა, ვადაგასული ნიშნები, დიდი სხეულები

ქაოსი

მოვლენების 10-30% Drop, reorder, შეფერხებები 1-10 წთ
დამოკიდებულების გათიშვა (PSP/KYC) - სწორი fallback/შეცდომები

16) მიღება და გაშვება (go-live)

საბოლოო PRR (წარმოების მიმოხილვა) დასრულდა
კანარეის ჩართვა: 10% 25% - 50% - 100%
მანქანის გამოტოვება SLO სიგნალებზე (შეცდომები/ლატენტობა/429)

გამოქვეყნდა ინციდენტების საკონტაქტო მატრიცა და ესკალაციის გზა

Backlog CAPA მფრინავის შემდეგ ჩამოყალიბდა

17) ოპერაცია და მხარდაჭერა

Runbook/playbuks: „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 მორგებული და ტესტირებულია
განხორციელებულია ლიმიტები/კვოტები/რეტრაები/იდემპოტენტობა
პაგინაცია/კურსორი/დელტა მუშაობს მონაცემებზე
ვებჰუკი: ხელმოწერები, გამეორებები, DLQ/Replay შემოწმებულია
'problem + json', 'trace _ id' შეცდომები ყველა ლოგოში იჭრება
დაშბორდები/ალერტები გროვდება, OTel შედის
დატვირთვა/უარყოფითი/ქაოსის ტესტები
შერწყმა და მოხსენებები თანხვედრა ხდება, გაფორმებულია runbooks
PRR/კანარი/rollback გეგმა მზად არის, კონტაქტები მითითებულია

შედეგი

ეს ჩეკლისტი ხურავს API- ს ინტეგრაციის ტექნიკურ, ოპერაციულ და შესაბამისობას-ასპექტებს. გაიარეთ წერტილები ზემოდან ქვემოთ, ავტომატურად შეამოწმეთ ლიმიტები, იდემპოტენტობა და ვებჰუკები, ჩართეთ დაკვირვება და დაბრუნების გეგმა - და თქვენი გაშვება მოხდება პროგნოზირებულად, წარმოების დროს „სიურპრიზების“ გარეშე.

API ინტეგრაციის Checlist

უარყოფითი

ქაოსი

ხელახალი პოლიტიკა (ფსევდო)

შედეგი

დაგვიკავშირდით

სწრაფი კავშირი

ვიდეო მალე განახლდება

ჩვენ ახლა ძალიან დაკავებული ვართ პროექტებით