API ეკოსისტემები

(განყოფილება: ეკოსისტემა და ქსელი)

1) მიზნები და პრინციპები

• სწრაფი, პროგნოზირებადი ინტეგრაცია (დროის ინტეგრაცია).
• საიმედოობა და მასშტაბურობა (SLO, QoS, backpressure).
• უსაფრთხოება და მარეგულირებელი რეგულაციების დაცვა (მინიმალური უფლებები, აუდიტი).
• ევოლუცია ავარიის გარეშე (ვერსიები, თავსებადობა, იჩეფლაგები).

პრინციპები: contract-first, მონაცემთა შემცირება, იდემპოტენტობა, observability-by-default, გამოშვების „ორი სიჩქარე“ (core vs experimental).

2) API ტაქსონომია

1. REST/HTTP - სინქრონული CRUD/სამეთაურო ოპერაციები, idempotence-key, pagination/cursors.
2. GRPC/QUIC - დაბალი ლატენტობა, ნაკადები, ორობითი ოქმები.
3. Events (Pub/Sub) - აფეთქების ღუმელის მოვლენები ('deposit.', 'payout.', 'bridge.', 'risk.').
4. Webhooks - საპირისპირო შეტყობინებები ხელმოწერებითა და მოხსენებებით.
5. GraphQL (შეზღუდული) - ძირითადი კითხვა მატერიალიზებული ფანჯრების თავზე.
6. ადმინ/მეტა - კატალოგები, ვერსიები, სტატუსები, გასაღებები, კვოტები.

დაშვების დონე: Public (შეზღუდული მეთოდები/კითხვა), Partner (ნაგავი და კვოტები), Internal (პირადი კონტურები).

3) კონტრაქტები და სქემები

OpenAPI/AsyncAPI/Protobuf IDL არის ჭეშმარიტების ერთი წყარო.
Data Contracts - თავსებადობის ტესტები, სქემების ლინზები, „გატეხილი“ ველების აკრძალვა MAJOR- ის გარეშე.
კატალოგები: აქტივები/ქსელები, PSP/მეთოდები, რეგიონები/იურისდიქციები, SDK ვერსიები, შესაძლებლობების დროშები.

მინიმალური REST კონტრაქტი (OpenAPI ფრაგმენტი)

yaml openapi: 3. 0. 3 info: { title: Ecosystem Core API, version: "2. 6. 0" }
paths:
/v2/payouts:
post:
operationId: createPayout parameters:
- in: header name: Idempotency-Key required: true schema: { type: string, maxLength: 64 }
requestBody:
required: true content:
application/json:
schema:
$ref: "#/components/schemas/PayoutRequest"
responses:
"202": { $ref: "#/components/responses/Ack" }
"409": { description: "Duplicate (idempotent)" }
components:
schemas:
PayoutRequest:
type: object required: [amount, currency, destination]
properties:
amount:  { type: string, pattern: "^[0-9]+(\\.[0-9]{1,9})?$" }
currency: { type: string, example: "USD" }
destination: { type: string }
metadata: { type: object, additionalProperties: true }

მოვლენები (AsyncAPI)

yaml asyncapi: 2. 6. 0 info: { title: Ecosystem Events, version: "1. 9. 0" }
channels:
payout. finalized:
subscribe:
message:
name: PayoutFinalized payload:
type: object required: [id, ts, amount, currency, status, signature]
properties:
id: { type: string }
ts: { type: string, format: date-time }
amount: { type: string }
currency: { type: string }
status: { type: string, enum: ["finalized","failed"] }
signature: {type: string} # source signature

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

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH - თავსებადი; MAJOR - პარალელური ვერსიები ('/v1 ', '/v2') + გადამყვანები.
დეპრესიის პოლიტიკა: ფანჯარა 90 დღე, მხარდაჭერის „ორი ხაზი“, კონტრაქტების ავტომატური შეტყობინებები.
Feature Flags: რეგიონების/პარტნიორების მიხედვით ველების/მეთოდების ჩართვა/გამორთვა.
კაპიტალური ნეგოტიაცია: მხარდაჭერილი პროფილების გამოცხადება ხელით.

5) Idempotence, შეკვეთები და კურსორები

• Exactly-once სემანტიკა outbox/inbox და idempotent კონსიუმერის საშუალებით.
• კურსორების პაგინაცია: 'შემდეგი _ cursor', ჩანართების/წაშლის წინააღმდეგობა.
• დახარისხება და ფილტრები - სტაბილური, აშკარად დოკუმენტირებული.

6) უსაფრთხოება და ნდობა

mTLS (მომსახურება და მომსახურება), სერიალების დაფა და გასაღებების როტაცია.
OAuth2/OIDC (client credentials, JWT მოკლე TTL), PoP/DPoP არხზე მითითებისთვის.
Webhook ხელმოწერები (NMAS/გასაღების ვერსია/დრო), გამეორებისგან დაცვა.
RBAC/ABAC და POLP: ნაკრები, org _ id/tenant _ id, ობიექტის/ოპერაციის ლიმიტები.
DLP/PII მინიმიზაცია: ეტიკეტებში/ლოგოებში PII აკრძალვა, იდენტიფიკატორის ტოქსიკაცია.
Rate-limits და WAF: per org/route/region, დაცვა აბუსისგან.

გასაღების პოლიტიკის მაგალითი (YAML)

yaml auth:
oauth2:
issuer: "https://auth. ecosys"
jwks_uri: "https://auth. ecosys/.well-known/jwks. json"
token_ttl_s: 900 mtls:
required_for: ["internal","partner_p0"]
scopes:
- name: payouts:write
- name: payouts:read
- name: events:subscribe

7) კვოტები, QoS და backpressure

კლასები QoS: P0 (გადახდა/ხიდი/საბოლოო), P1 (სასურსათო), P2 (bulk/არქივი).
კვოტები/ლიმიტები: RPS, concur-requests, bytes/sec, თემა/წვეულება მოვლენებისთვის.
Admission Control: „ძვირადღირებული“ მოთხოვნების ადრეული გადახრა, heavy-query-guard.
Backpressure: ნიშნები/სესხები, ხაზები DLQ- ით, retray ერთად jitter.

კვოტების პოლიტიკა

yaml quotas:
partner_default:
rps: 200 concurrent: 100 webhooks_outbound_rps: 50 p0:
rps: 100 p95_latency_ms: 400

8) დაკვირვება: SLI/SLO, მეტრიკა, ტრეკები

• p95/99 latency по маршрутам, Success Rate, Error budget burn, Queue-lag p95, Freshness webhooks, Delivery success%.
• Contract Compliance% (სქემები/ხელმოწერები).
• Webhook retry/dropped%.

SLO (სახელმძღვანელო): P0 p95-400 ms, Availability-99. 95%; Webhook delivery p95 ≤ 2 с; Events freshness p95 ≤ 60 с.

მეტრიკა: ლატენტობის ჰისტოგრამები, შეცდომების კოდები, პასუხების ზომა, RPS, per-tenant.
Trace: 'Trace _ id' (edge-gateway- ის სერვისის მიერ DB/event/webhook).
ლოგოები: სტრუქტურირებული, PII- ის გარეშე, კორელაცია 'request _ id'.

9) განთავისუფლების ნიმუშები დასრულების გარეშე

Blue-Green/Canary ერთად SLO კარიბჭეები და outlier-ejection.
Schema-first ევოლუცია: მხოლოდ ველების დამატება, ძველი მომხმარებლებისთვის გადამყვანები.
BD მიგრაციის Zero-downtime: ონლაინ DDL, ორმხრივი გადამყვანი.
ცვლილებების კონტროლი: Timelock, აუდიტი და თავსებადობის რეესტრი.

10) კატალოგები და რეესტრები

API/ვერსიების რეესტრი

sql
CREATE TABLE api_registry(
name TEXT, kind TEXT,      -- rest    grpc    events    webhook version TEXT, status TEXT,   -- active    canary    deprecated    retired slo JSONB, owner TEXT,
PRIMARY KEY (name, version)
);

მოვლენების კატალოგი

sql
CREATE TABLE event_catalog(
topic TEXT PRIMARY KEY,
schema_version TEXT,
qos TEXT,
retention_days INT,
pii BOOLEAN DEFAULT false
);

გასაღებები/ნაკრები

sql
CREATE TABLE api_keys(
key_id TEXT PRIMARY KEY,
org_id TEXT, scopes TEXT[], status TEXT, expires_at TIMESTAMPTZ
);

11) ტესტირება და კონტრაქტების შესრულება

Contract-tests: მომხმარებელთა წარმოება, სქემების შესაბამისობა, negative- _ cases.
მოვლენების ტესტები: გამეორების/ხელახალი დარღვევის წინააღმდეგობა.
Chaos/Lat-tests: ზარალის ინექცია/ჯიტერი, ნელი ნაკადი.
Security-tests: ვებჰუკების ხელმოწერები, კლავიშების როტაცია, გამეორების შეტევები.
შესრულების პროფილები: SLA სპაიკები, ცხელი მარშრუტები, DA/დამოკიდებულების ხიდი.

12) ინტერფეისის მაგალითები

Webhooks (ხელმოწერა და შენიშვნები)

yaml webhooks:
deliveries:
retry:
attempts: 5 backoff_ms: [200, 800, 1600, 3200, 6400]
jitter: true signature:
alg: "HMAC-SHA256"
header: "X-ECO-Signature"
timestamp_header: "X-ECO-Timestamp"
tolerance_s: 300

GraphQL (საერთო კითხვა, მხოლოდ კითხვა)

graphql type Query {
payouts(status: [Status!], first: Int!, after: String): PayoutConnection!
}

gRPC (მოვლენების ნაკადი)

proto service EventStream {
rpc Subscribe(SubscribeRequest) returns (stream Event);
}

13) პროცესები და როლები

API Owner - კონტრაქტი/ვერსია/SLO/კვოტები.
უსაფრთხოება - გასაღებები/ხელმოწერები/აუდიტი/DLP.
SRE/Ops - დაშბორდები, ალერტები, capacity.
Partner Success - ონბორდი, ლიმიტები, ფიჩეფლაგები.
კომპლექსი - იურისდიქცია, სანქციები, მოხსენებები.

14) დაშბორდი

Core API: latency/error/RPS მარშრუტებზე და ტენტანტებზე.
Webhooks: delivery p95, retries, drops, ხელმოწერები.
Events: freshness, lag, consumer health, DLQ.
უსაფრთხოება: განთავისუფლების გასაღებები, ხელმოწერები, უარი ეთქვა მოთხოვნებზე.
მთავრობის: აქტიური ვერსიები/დეპრესიები, კონტრაქტების თავსებადობა.

15) Playbook ინციდენტები

A. ზრდა p95 ლატენტობა P0

1. ჩართეთ პრიორიტეტი P0 და P2-throttle; 2) კარიბჭეების მასშტაბები;

2. კითხვების ნაწილის ქეში გადატანა; 4) ცხელი მარშრუტების ანალიზი.

B. Delivery webhook

1. ხელმოწერების/საათის ცვლის გადამოწმება, 2) გაზარდოს რეტრაები/ტაიმაუტები,

2. ჩართეთ batchi, 4) დროებით გადასვლა endpoint ტყვიაზე.

C. Drift კონტრაქტები

1. ჩართეთ „მკაცრი რეჟიმი“ (შეწყვიტეთ არასწორი შეტყობინებები),

2. აცნობეთ პროდიუსერს, 3) გაათავისუფლეთ ადაპტერი, 4) პოსტ-mortem, განაახლეთ ლინტერი.

დ. გასაღების/სერტის კომპრომისი

1. Revoke/rotate, 2) გადააკეთეთ ვებჰუკი, 3) აუდიტი, 4) აცნობეთ პარტნიორებს.

E. გამეორების აფეთქება/დუბლი

1. შეამოწმეთ Idempotency-Key/TTL, 2) დედაპლატის გაძლიერება, 3) შეზღუდეთ „ხმაურიანი“ წყარო.

16) განხორციელების შემოწმების სია

1. აღწერეთ კონტრაქტები (OpenAPI/AsyncAPI/IDL), ჩართეთ linters და CI.
2. Auth (OAuth2/OIDC, mTLS) კონფიგურაცია, ვებჰუკების ხელმოწერა, გასაღების როტაცია.
3. შეიყვანეთ კვოტები/QoS/limites, heavy-query-guard და backpressure.
4. გაზარდეთ დაკვირვება: SLI/SLO, ბილიკები, დაშბორდები, ალერტები.
5. გამოცემების ორგანიზება: canary/blue-green, schema-first მიგრაცია.
6. დაიწყეთ ვერსიების/მოვლენების/გასაღებების კატალოგი და დეპრესიის პროცესები.
7. ჩაატარეთ chaos/perf/უსაფრთხოების ტესტები, შეადგინეთ playbuks.
8. რეგულარულად გადაამოწმეთ მონაცემების მინიმალიზაცია და მარეგულირებლის შესაბამისობა.

17) გლოსარიუმი

Contract-first - API- ის დიზაინი ოფიციალური კონტრაქტების საშუალებით კოდამდე.
Idempotency-Key არის გასაღები, რომელიც ოპერაციის განმეორებას უსაფრთხო ხდის.
AsyncAPI - ღონისძიების ინტერფეისების სპეციფიკაცია.
QoS არის ხარისხის კლასი/მომსახურების პრიორიტეტი.
DLQ არის „მკვდარი ხაზი“ პრობლემური შეტყობინებებისთვის.
Error budget burn - შეცდომის ბიუჯეტის „დაწვის“ სიჩქარე SLO- სთან დაკავშირებით.

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