ოპერაციები API ინტერფეისის საშუალებით

(განყოფილება: ოპერაციები და კონტროლი)

1) დანიშვნა და პრინციპები

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

პრინციპები:

Contract-first: პირველი სპეციფიკაცია (OpenAPI/JSON Schema/AsyncAPI), შემდეგ განხორციელება.
Secure-by-default: მინიმალური ნაკრები, მოკლე TTL, miutual-TLS/ხელმოწერები.
Observable: end-to-end კვალი და მეტრიკა SLA.
Idempotent: გამეორება უსაფრთხოა.
Backwards-compatible: ევოლუცია „გატეხილი“ ცვლილებების გარეშე.
Auditable: კრიპტოგრაფიულად დადასტურებული ფაქტები (ქვითრები).

2) კონტრაქტი და მოდელები (რეფერენდუმი)

OpenAPI sync მოთხოვნებისთვის; AsyncAPI მოვლენებისთვის/ვებჰუკებისთვის.
სავალდებულო ველები თითოეულ რესურსში: 'id', 'version', 'created _ at', 'განახლება _ at', 'tenant', 'region', 'trace _ id'.

ხელშეკრულების ფრაგმენტის მაგალითი

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) ავთენტიფიკაცია, ავტორიზაცია, კოპირება

OAuth2/OIDC მომხმარებლებისთვის/პარტნიორებისთვის; client-credentials/JWT для S2S.
Scopes/რესურსების როლები: 'payments. write`, `catalog. read`, `audit. export`.
ReBAC: წვდომა „მფლობელობაში“ (ტენანტი/ანგარიში/sab ანგარიში).
JIT საიდუმლოებები: ხანმოკლე ნიშნები, მოწყობილობის/ქვესახეობის/რეგიონის კავშირი.
Device posture & mTLS კრიტიკული ოპერაციებისთვის (გადახდები, გასაღებები).

4) Idempotence და „ზუსტად ერთხელ“

Idempotency-Key (სათაური) + დედაპლატი '(key, account, მარშრუტი)' TTL ფანჯარაში.
Outbox/CDC მოვლენების გამოსაცემად გარანტირებული მიწოდებაა.
Exactly-once-effects: გვერდითი მოვლენები ფიქსირდება გარიგების ჟურნალის საშუალებით; გამეორება იწვევს იმავე „ქვითარს“ ('receipt _ hash').
რეტრის პოლიტიკა: ექსპონენციალური სარეზერვო ოფი, ჯიტერი, მაქსიმალური ფანჯრები.

5) ლიმიტები, კვოტები, პრიორიტეტები

Rate limits: per-key/tenant/route/region; „რბილი“ (429) და „მკაცრი“ (შემცირება).
კვოტები/ბიუჯეტები: ყოველთვიური/ყოველდღიური ქუდი, ვებჰუკი 'ÉtaCapReached'.
Fair-use: ტენდერების პრიორიტეტი მომსახურების დონეზე (Gold/Silver/Bronze).
ბურსტის ბუფერები: მოკლე ადიდებები მეზობლების დეგრადაციის გარეშე.

6) პაგინაცია, ფილტრები, ნიმუშები

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.
დროული შერჩევა ('from', 'to', 'watermark') ჟურნალებისთვის/გარიგებისთვის.
Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.
Consistence hints: 'snapshot _ at '/' as _ of' რეპორტირების API- სთვის.

7) ვერსია და თავსებადობა

SemVer: `v1`, `v1. 1 '(გაფართოება),' v2 '- მხოლოდ ახალი მარშრუტებით/ნეიმსპეისებით.
ევოლუციის წესები: მხოლოდ ველების/მნიშვნელობების დამატება, ფანჯრის მეშვეობით „დეპრესია - რემოვა“.
Compatibility tests: consumer-driven.

8) მოვლენები, ვებჰუკი და ქვითრები

AsyncAPI აღწერს თემებს/payload/ხელმოწერებს.
ხელმოწერა: HMAC/EdDSA, სათაურები 'X-Signature', 'X-Nonce', 'X-Timestamp' (ვიწრო ფანჯარა).
ქვითრები: 'receipt _ hash' და DSSE ხელმოწერა კრიტიკულ მოვლენებზე (გადახდები, ცვლილებები RTP/limites, ფასების სიები).
Retrai და dedup: idempotence 'idempotency _ key '/' event _ id'.
DLQ/კარანტინი: არასასურველი/განმეორებითი შეტყობინებები მიზეზებით.

9) დაკვირვება და ხარისხი

Traces: სავალდებულო 'trace _ id/span _ id' კარიბჭის/ბიზნეს მოვლენების/ვებჰუკების საშუალებით.
Metrics: წვდომა, p50/p95/p99, error-rate, retry-rate, cost per 1k.
ლოგები: სტრუქტურირებული, საიდუმლოებების გარეშე/PII; ეტიკეტები 'tenant/region/version'.
SLO/ალერტები: SLO ორიენტირებული პირობები და მანქანის რუნები (pause/re-route/rollback).

10) სტატუსის შეცდომები და სემანტიკა

2xx - წარმატება (202 ასინქრონული ოპერაციებისთვის).
4xx - კლიენტის დანაშაული (422 - შესაბამისობა, 409 - კონფლიქტი/იდემპოტენტობა, 429 - ლიმიტები).
5xx არის დროებითი პრობლემები.
შეცდომის სხეული: 'code', 'მესიჯი', 'trace _ id', 'hint', 'retry _ after? ".
UX პარტნიორებისთვის: ცხრილი „რა უნდა გააკეთო“ თითოეული შეცდომისთვის.

11) პოლიტიკა-კოდი (OPA/ABAC)

ცენტრალიზებული ავტორიზაცია: „ვინ/რა/სად/როდის/რატომ“.
პოლიტიკოსები Git- ში, კოდის შურისძიებით, CI ტესტები (pre-flight: "დაუშვებს პოლიტიკას? »).
SoD ჩეკი: "შექმენით გადახდა" დამტკიცება ".

12) უსაფრთხოება, კონფიდენციალურობა, შესაბამისობა

PII მინიმიზაცია: ტოკენიზაცია/ნიღბები, პირველადი წვდომა მხოლოდ დამტკიცებული ჯობის საშუალებით.
საიდუმლოებები: Vault/KMS, მოკლე TTL, როტაცია; აკრძალული საიდუმლოების აკრძალვა.
დაშიფვრა: mTLS/TLS 1. 3, AES-GCM at-rest, HSTS/PKP სადაც შესაფერისია.
Jurisdiction-aware: მონაცემთა/გასაღებების ლოკალიზაცია.
აუდიტის ჟურნალები: WORM, მერკლის ნაჭრები, DSSE ხელმოწერები.

13) ოპერაცია: SLI/SLO და დაშბორდები

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

Per route/region ხელმისაწვდომობა.
ლატენტობა p95 (read/write).
ვებჰუკების (ქვითრების) წარმატება, მიწოდების გზა.
Error-rate/Retry-rate.
Cost per 1k მოთხოვნა და egress.

SLO (მაგალითი): 99. წვდომის 95%; p95-120/250 ms; ვებჰუკი - 99. 5 %/5 წუთი; P1 MTTR - 60 წთ

14) ცვლილების მენეჯმენტი (გამოშვებები/გამოტოვება)

Blue-Green/Canary საკეტები და კრიტიკული მარშრუტები.
ფიჩეფლაგები ქცევისთვის გამოშვების გარეშე.
Expand - Migrate - Contract სქემებისა და payload- ისთვის.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
არტეფაქტები: ხელმოწერილი სურათები/მანიფესტები, ვერსიების რეესტრი.

15) SDK, მომხმარებლები, „ქვიშის ყუთები“

ოფიციალური SDK (TS/Java/Python/Go) იგივე შეცდომებისა და რეაგირების სემანტიკით.
Sandbox გარემო ტესტის კლავიშებით/სერთიფიკატებით და PSP/KYC/შინაარსის პროვაიდერების სიმულატორებით.
Contract-tests შედის SDK CI, nightly თავსებადობა.

16) მონაცემთა მოდელი (გამარტივებული)

`api_key` `{id, tenant, scopes[], ttl, created_by}`

`rate_plan` `{tenant, quotas{route→cap}, burst, priority}`

`request_log` `{trace_id, route, actor, idempotency_key?, status, latency_ms, region, cost_unit}`

`webhook_receipt` `{event_id, endpoint, status, attempts, receipt_hash, signature}`

`policy` `{version, rules, signer, dsse}`

17) RACI

რეგიონი	Responsible	Accountable	Consulted	Informed
კონტრაქტი/ვერსიები	Platform/API	CTO	Product, Clients	Partners
ავტორიზაცია/პოლიტიკა	Security/IAM	CISO	Legal, Ops	Audit
დაკვირვება/SLO	SRE	Head of Eng	Data, FinOps	All
ვებჰუკი/ქვითრები	Integration	COO	Partners, Finance	Compliance
SDK/ქვიშის ყუთები	DevEx	CTO	SRE, Product	Partners

18) ხარისხის მეტრიკა

Contract Drift: 0 „დაშლის“ ცვლილებები დეპრესიის გარეშე.
Idempotency Error Rate: ≤ 0. 01%.
Webhook Success: ≥ 99. 5%, lag p95-60.
Auth Fail vs Abuse: მავნე ბლოკების პროპორცია, სამიზნე დონის ხმაური.
Cost/1k: კონტროლი მარშრუტებსა და რეგიონებში (ბიუჯეტები/კაპი-ალერტები).
SDK Adoption: ტრეფიკის წილი ოფიციალური SDK- ით.

19) ინციდენტების ფლეიბუკი

Spike 429/limites: გაზარდეთ ქუდი გოლდისთვის, trotling „ხმაურიანი“ გასაღებები, პარტნიორთან კომუნიკაცია.
WebhookLag: გაზარდეთ workers/batchs, პრიორიტეტული რიგები, დროებით გამორთეთ არჩევითი ვებჰუკები.
PriceMismatch (catalog/FX/Tax): ვერსიების შერიგება, ქეში ინვალიდობა, არტეფაქტის გამოტოვება, კომპენსაცია.
PSP Outage: მარშრუტის გადართვა, „ნაცრისფერი“ გარიგების საკარანტინო, რაფები.
Compromise API-key: დაუყოვნებელი მიმოხილვა, როტაცია, ბოლო 30 დღის აუდიტი.

20) iGaming/fintech სპეციფიკა

RTP/Limits API: მხოლოდ დანაყოფები და პროფილის ვერსიები; ცვლილებები - ქვითრებით.
გადახდა/გადახდა: 202 + ვებჰუკი ხელმოწერებით; იდემპოტენტურობა შეკვეთის გასაღებად.
Affiliates: Conversium- ის დედაპლატი, სადავო ესკიზი, ხელმოწერილი მოხსენებები.
საპასუხისმგებლო თამაში: გამოიფინა „guardrails API“ ლიმიტებისა და RG მოვლენებისთვის.

21) განხორციელების სია

აღწერილია კონტრაქტი (OpenAPI/AsyncAPI), CI სავალდებულო და consumer-tests.
OAuth2/OIDC, ნაკრები, JIT საიდუმლოებები და mTLS კრიტიკული მარშრუტებისთვის.
დაინერგა idempotence, retrai, DLQ და კარანტინი.
ლიმიტები/კვოტები/პრიორიტეტები და ქუდების ალერტები.
კურსორების პაგინაცია, თანმიმდევრული ნიმუშები 'as _ of'.
ვერსია და დეპრესიის პოლიტიკა.
ვებჰუკი ხელმოწერებით/ქვითრებით, რეპლიკებით და დედაპლატით.
კვალი/მეტრიკა/ლოგები, SLO და რუნები.
WORM ჟურნალები, DSSE ხელმოწერები, მერკლის ნაჭრები.
SDK, sandbox, სიმულატორები, კოდის მაგალითები და „how-to“.

22) FAQ

რატომ არის 202 გრძელი ოპერაციებისთვის?
იმისათვის, რომ არ შეინარჩუნოთ კავშირი და უზრუნველყოთ საიმედო რეაგირება/ქვითარი ვებჰუკის საშუალებით.

საჭიროა ორივე: OpenAPI და AsyncAPI?
დიახ: sync ბრძანებების/მოთხოვნებისთვის, async სახელმწიფოების მოვლენებისთვის/კოორდინაციისთვის.

როგორ ავარიდოთ თავი ცვლილებებს?
წესი „მხოლოდ დამატებები“, deprecate - observe - remove, მომხმარებელთა კონტრაქტის ტესტები.

სად უნდა შეინახოთ ქვითრები?
WORM ზონაში ხელმოწერებით; 'receipt _ hash' ბრუნდება კლიენტთან და იბლოკება მოთხოვნით.

რეზიუმე: API- ს საშუალებით ოპერაციები არის კონტრაქტისა და ექსპლუატაციის დისციპლინა: დაშვების მკაცრი მოდელი და იდემპოტენტურობა, ლიმიტები და ვერსიები, დაკვირვება და SLO, ხელმოწერები და ქვითრები. დაამატეთ ქვიშის ყუთები და SDK - და პარტნიორები სწრაფად ინტეგრირდებიან, უსაფრთხოდ და პროგნოზირებად, ხოლო ბიზნესი მასშტაბური იქნება ხარისხისა და შესაბამისობის დაკარგვის გარეშე.

ოპერაციები API ინტერფეისის საშუალებით

ხელშეკრულების ფრაგმენტის მაგალითი

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

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

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

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