Ekosistemanyň API-leri

(Bölüm: Ekosistema we Tor)

1) Maksatlar we ýörelgeler

• Çalt, öňünden aýdyp boljak integrasiýa (time-to-integration ↓).
• Ygtybarlylygy we ululygy (SLO, QoS, backpressure).
• Howpsuzlyk we düzgünleşdirijiligiň berjaý edilmegi (iň pes hukuklar, audit).
• Döwülmezden ewolýusiýa (wersiýalar, gabat gelmek, aýratynlyklar).

Ýörelgeler: contract-first, maglumatlary minimallaşdyrmak, idempotentlik, observability-by-default, "iki tizlik" relizleri (core vs experimental).

2) API taksonomiýasy

1. REST/HTTP - sinhron CRUD/buýruk amallary, idempotency-key, pagination/cursors.
2. gRPC/QUIC - pes gizlinlik, akym, ikili teswirnamalar.
3. Events (Pub/Sub) - domen wakalary ('deposit.', 'payout.', 'bridge.', 'risk.').
4. Webhooks - gollar we retralar bilen yzyna bildirişler.
5. GraphQL (çäkli) - materiallaşdyrylan penjireleriň üstünde okamak.
6. Admin/Meta - kataloglar, wersiýalar, statuslar, açarlar, kwotalar.

Giriş derejeleri: Public (çäklendirilen usullar/okamak), Partner (satyn almak we kwotalar), Internal (şahsy konturlar).

3) Şertnamalar we shemalar

OpenAPI/AsyncAPI/Protobuf IDL - hakykatyň ýeke-täk çeşmesi.
Data Contracts - laýyklyk synaglary, shema linterleri, MAJOR-syz "döwýän" meýdanlary gadagan etmek.
Kataloglar: aktiwler/torlar, PSP/usullar, sebitler/ýurisdiksiýalar, SDK wersiýalary, mümkinçilikleriň baýdaklary.

Iň az REST şertnamasy (OpenAPI bölegi)

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 }

Wakalar (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) Wersiýalaşdyrmak we gabat gelmek

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH - yza gabat gelmek; MAJOR - paralel wersiýalar ('/v1 ', '/v2') + adapterler.
Deprecation policy: penjire ≥ 90 gün, "iki setir" goldaw, şertnamalar boýunça awtomatiki habarnamalar.
Feature Flags: Sebitler/hyzmatdaşlar boýunça meýdançalary/usullary açmak/öçürmek.
Capability Negotiation: el çarpylanda goldanýan profilleri yglan etmek.

5) Görelde, tertip we kursorlar

Toparlar üçin idempotency-Key (create/cancel), TTL açarlary ≥ 72 sagat.
Exactly-once semantika outbox/inbox we idempotent konsumer arkaly.
Kursor bilen paginasiýa: 'next _ cursor', goýma/aýyrma garşylygy.
Sortlamak we süzgüçler - durnukly, anyk dokumentleşdirilen.

6) Howpsuzlyk we ynam

mTLS (service service), sertleriň aýlanmagy we açarlaryň aýlanmagy.
OAuth2/OIDC (client credentials, JWT, gysgaça TTL), PoP/DPoP.
Webhook gollary (NMAS/açar wersiýasy/wagt), gaýtalanmakdan goramak.
RBAC/ABAC we PoLP: obýekt/amal üçin satyn alyşlar, org_id/tenant_id, çäklendirmeler.
DLP/PII-iň minimallaşdyrylmagy: PII-iň belliklerde/ýazgylarda gadagan edilmegi, kesgitleýjileriň belligi.
Rate-limits we WAF: per org/route/region, abuse goragy.

Açar syýasatynyň mysaly (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) Kwotalar, QoS we backpressure

QoS synplary: P0 (tölegler/köpri/gutarmak), P1 (azyk önümleri), P2 (bulk/arhiw).
Kwotalar/çäkler: RPS, concur-requests, bytes/sec, wakalar üçin mowzuk/partiýa.
Admission control: "gymmat" haýyşlaryň irki ret edilmegi, heavy-query-guard.
Backpressure: tokenler/karzlar, DLQ bilen nobatlar, jitter bilen retraýlar.

Kwota syýasaty

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

8) Syn edilişi: SLI/SLO, metrikler, yzarlamalar

• p95/99 latency по маршрутам, Success Rate, Error budget burn, Queue-lag p95, Freshness webhooks, Delivery success%.
• Contract Compliance% (shemalar/gollar).
• Webhook retry/dropped%.

SLO: P0 p95 ≤ 400 ms, Availability ≥ 99. 95%; Webhook delivery p95 ≤ 2 с; Events freshness p95 ≤ 60 с.

Metrikler: gizlinlik gistogrammalary, ýalňyşlyk kodlary, jogaplaryň ululygy, RPS, per-tenant.
Söwda: 'trace _ id' (edge → gateway → service → DB → event/webhook) arkaly.
Loglar: gurluşly, PII-siz, 'request _ id' bilen baglanyşyk.

9) Taşlamasyz çykarylýan patternler

SLO we outlier-ejection bilen Blue-Green/Canary.
Schema-first ewolýusiýasy: Diňe meýdanlary goşmak, köne müşderiler üçin adapterler.
Nol-downtime migrasiýasy DB: online-DDL, iki taraplaýyn konwerterler.
Üýtgeşmelere gözegçilik etmek: timelock, audit we laýyklyk sanawy.

10) Kataloglar we reýestrler

API/wersiýalaryň sanawy

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)
);

Wakalar katalogy

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

Açarlar/Satyn almalar

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

11) Synag we şertnamalara laýyklyk

Contract-tests: Müşderi öndürmek, shemalary tassyklamak, negative-_cases.
Wakalaryň replay-synaglary: gaýtalanmalara/tertipleşdirmäge garşylygy.
Chaos/Lat-tests: ýitgiler/jitter sanjymlary, haýal döwür.
Security-tests: webhook gollary, açarlaryň aýlanmagy, gaýtalanýan hüjümler.
Performance-profilleri: SLA-yslamalar, "gyzgyn" ugurlar, DA/garaşlylyk köprüsi.

12) Interfeýsleriň mysallary

Webhooks (gol we retralar)

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 (umumy okamak, diňe okamak)

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

gRPC (wakalar akymy)

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

13) Prosesler we rollar

API Owner - şertnama/wersiýa/SLO/kwotalar.
Howpsuzlyk - açarlar/gollar/audit/DLP.
SRE/Ops - daşbordlar, alertler, capacity.
Partner Success - onbording, limitler, ficheflaglar.
Compliance - ýurisdiksiýalar, sanksiýalar, hasabatlylyk.

14) Daşbordlar

Core API: latency/error/RPS marşrutlar we tentantlar boýunça.
Webhooks: delivery p95, retries, drops, gollar.
Events: freshness, lag, consumer health, DLQ.
Howpsuzlyk: gutarmak üçin açarlar, gollar, ret edilen soraglar.
Governance: işjeň wersiýalar/deprekeýtler, şertnamalaryň laýyklygy.

15) Playbook hadysalary

A. P95 gizlinligiň ýokarlanmagy P0

1. P0 we P2-throttle prioritetini öz içine alyň; 2) şlýuzlary masştablamak;

2. okamagyň bir bölegini kesele geçirmek; 4) "gyzgyn" ugurlary seljermek.

B. delivery webhook

1. Gollary/sagatlyk çalşygy barlaň, 2) retralary/wagtlary köpeltmek,

2. 4) pull-endpointe wagtlaýyn geçmek.

C. Drift şertnamalary

1. "strict mode" (nädogry habarlary kesmek),

2. öndürijä habar bermek, 3) adapteri çykarmak, 4) post-mortem, linterleri täzelemek.

D. Açaryň/sertiň bozulmagy

1. Revoke/rotate, 2) webhuklary täzeden oýnamak, 3) audit, 4) hyzmatdaşlara habar bermek.

E. Gaýtalamalaryň/dubllaryň partlamasy

1. Idempotency-Key/TTL barlaň, 2) baby güýçlendiriň, 3) "şowhunly" çeşmäni çäklendiriň.

16) Girizmegiň çek-sanawy

1. Şertnamalary beýan etmek (OpenAPI/AsyncAPI/IDL), linterleri we CI-leri goşmak.
2. Auth (OAuth2/OIDC, mTLS), webhook gollaryny, açar aýlanyşyny sazla.
3. Kwotalary/QoS/çäkleri, heavy-query-guard we backpressure giriň.
4. Syn edilişini ýokarlandyrmak: SLI/SLO, ýollar, daşbordlar, aladalar.
5. Neşirleri guramak: canary/blue-green, schema-first migrasiýasy.
6. Wersiýalar/wakalar/açarlar katalogyny we deprekeýt amallaryny başla.
7. Chaos/perf/security-synaglary geçirmek, pleýbuklary resmileşdirmek.
8. Maglumatlaryň minimallaşdyrylmagyny we düzgünleşdirijä laýyklygyny yzygiderli gözden geçirmeli.

17) Sözlük

Contract-first - API-ni koda çenli resmi şertnamalar arkaly dizaýn etmek.
Idempotency-Key - amalyň gaýtalanmagyny howpsuz edýän açar.
AsyncAPI - waka interfeýsleriniň aýratynlygy.
QoS - hyzmatyň hili/ileri tutulýan synpy.
DLQ - problemaly habarlar üçin "öli nobat".
Error budget burn - SLO bilen baglanyşykly ýalňyşlyklaryň býudjetini "ýakmagyň" tizligi.

Netije: Ekosistemanyň API-leri endpointleriň toplumy däl-de, eýsem şertnamalaryň, howpsuzlygyň, kwotalaryň we gözegçilik etmegiň dolandyrylýan ulgamy. Bu freýmworkdan soň, ekosistema çalt integrasiýalary, öňünden aýdyp boljak SLO we howpsuz ewolýusiýany - tor derejesinden we hakykylaşdyrmadan wakalaryň akymyna we hasabatlylyga çenli alýar.