API ekosistemləri

(Bölmə: Ekosistem və Şəbəkə)

1) Məqsədlər və prinsiplər

• Sürətli, proqnozlaşdırıla bilən inteqrasiya (time-to-integration ↓).
• Etibarlılıq və miqyaslı (SLO, QoS, backpressure).
• Təhlükəsizlik və tənzimləmə (minimum hüquqlar, audit).
• Arızasız təkamül (versiyalar, uyğunluq, ficheflages).

Prinsiplər: contract-first, məlumatların minimuma endirilməsi, idempotentlik, observability-by-default, «iki sürət» buraxılışları (core vs experimental).

2) API taksonomiyası

1. REST/HTTP - sinxron CRUD/komanda əməliyyatları, idempotency-key, pagination/cursors.
2. gRPC/QUIC - aşağı gecikmə, axınlar, ikili protokollar.
3. Events (Pub/Sub) - domen hadisələri ('deposit.', 'payout.', 'bridge.', 'risk.').
4. Webhooks - imzalar və retralar ilə əks bildirişlər.
5. GraphQL (məhdud) - materiallaşdırılmış vitrinlərin üzərində oxu yığma.
6. Admin/Meta - kataloqlar, versiyalar, statuslar, açarlar, kvotalar.

Giriş səviyyələri: Public (məhdud üsullar/oxu), Partner (satınalmalar və kvotalar), Internal (şəxsi konturlar).

3) Müqavilələr və sxemlər

OpenAPI/AsyncAPI/Protobuf IDL - həqiqətin vahid mənbəyidir.
Data Contracts - uyğunluq testləri, sxem linterləri, MAJOR olmadan «sındırıcı» sahələrin qadağan edilməsi.
Kataloqlar: aktivlər/şəbəkələr, PSP/metodlar, regionlar/yurisdiksiyalar, SDK versiyaları, fürsət bayraqları.

Minimum REST müqaviləsi (OpenAPI parçası)

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 }

Hadisələr (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) Version və uyğunluq

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH - geri uyğun; MAJOR - paralel versiyalar ('/v1 ', '/v2') + adapterlər.
Deprecation policy: pəncərə ≥ 90 gün, «iki xətt» dəstək, avtomatik müqavilə bildirişləri.
Feature Flags: Regionlar/tərəfdaşlar üzrə sahələri/metodları açmaq/söndürmək.
Capability Negotiation: əl sıxarkən dəstəklənən profillərin elanı.

5) İdempotentlik, sifarişlər və kursorlar

Komandalar üçün Idempotency-Key (create/cancel), TTL açarları ≥ 72 saat.
Exactly-once outbox/inbox və idempotent konsumer vasitəsilə semantika.
Pagination kursor: 'next _ cursor', insert/silinməyə davamlı.
Çeşidləmə və filtrlər - sabit, açıq sənədləşdirilmiş.

6) Təhlükəsizlik və etimad

mTLS (service service), sertlərin pininqi və açarların rotasiyası.
OAuth2/OIDC (client credentials, qısa TTL ilə JWT), kanal bağlamaq üçün PoP/DPoP.
Webhook imzaları (NMAS/açar versiyası/vaxt), təkrarlama qorunması.
RBAC/ABAC və PoLP: alış-veriş, org_id/tenant_id, obyekt/əməliyyat limitləri.
DLP/PII-minimallaşdırma: etiketlərdə/loqlarda PII qadağası, identifikatorların tokenləşdirilməsi.
Rate-limits və WAF: per org/route/region, abuse qorunması.

Açar siyasəti nümunəsi (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) Kvotalar, QoS və backpressure

QoS sinifləri: P0 (ödənişlər/körpü/final), P1 (ərzaq), P2 (bulk/arxiv).
Kvotalar/limitlər: RPS, concur-requests, bytes/sec, mövzu/hadisələr üçün hissələr.
Admission control: «bahalı» sorğuların erkən sapması, heavy-query-guard.
Backpressure: tokenlər/kreditlər, DLQ ilə növbələr, jitter ilə retralar.

Kvota siyasəti

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

8) Müşahidə: SLI/SLO, metriklər, izlər

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

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

Metriklər: latentlik histoqramları, səhv kodları, cavab ölçüsü, RPS, per-tenant.
Traces: keçidli 'trace _ id' (edge → gateway → service → DB → event/webhook).
Log: strukturlaşdırılmış, PII olmadan, 'request _ id' ilə korrelyasiya.

9) Endirimsiz buraxılış nümunələri

SLO gates və outlier-ejection ilə Blue-Green/Canary.
Schema-ilk təkamül: yalnız sahələr əlavə, köhnə müştərilər üçün adapterlər.
Sıfır downtime miqrasiya DD: Online DDL, iki yönlü çeviricilər.
Dəyişikliklərə nəzarət: timelock, audit və uyğunluq reyestri.

10) Kataloqlar və reyestrlər

API/versiyalar reyestri

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

Hadisə kataloqu

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

Açarlar/satın almalar

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

11) Test və müqavilələrə uyğunluq

Contract-tests: müştəri istehsalı, sxemlərin təsdiqi, negative-_cases.
Hadisələrin replay testləri: təkrarlanmaya/yenidən nizamlanmaya qarşı müqavimət.
Chaos/Lat-tests: enjeksiyon itkisi/jitter, yavaş yüz.
Security-tests: vebhuk imzaları, açarların rotasiyası, təkrar hücumlar.
Performance profilləri: SLA spikes, «isti» marşrutlar, DA/körpü asılılığı.

12) Interfeys nümunələri

Webhooks (imza və 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 (oxu yığma, yalnız oxu)

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

gRPC (hadisə axını)

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

13) Proseslər və rollar

API Owner - müqavilə/versiya/SLO/kvotalar.
Security - açarlar/imzalar/audit/DLP.
SRE/Ops - dashboard, alert, capacity.
Partner Success - onbordinq, limitlər, fiziki ifadələr.
Compliance - yurisdiksiyalar, sanksiyalar, hesabatlar.

14) Daşbordlar

Core API: marşrutlar və tentantlar üzrə latency/error/RPS.
Webhooks: delivery p95, retries, drops, imzalar.
Events: freshness, lag, consumer health, DLQ.
Təhlükəsizlik: sona çatma açarları, imzalar, rədd edilən sorğular.
Governance: aktiv versiyalar/deprekeytlər, müqavilələrin uyğunluğu.

15) Playbook hadisələr

A. Gecikmə artımı p95 P0

1. Prioritet P0 və P2-throttle daxil edin; 2) şlyuzları ölçmək;

2. bəzi oxunuşları cache keçmək; 4) «isti» marşrutların təhlili.

B. Payız delivery webhook

1. İmzaları/saat sürüşməsini yoxlayın, 2) gecikmələri/vaxtları artırın,

2. 4) müvəqqəti olaraq pull-end nöqtəsinə keçin.

C. drift müqavilələri

1. «strict mode» daxil edin (səhv mesajları kəsin),

2. istehsalçıya bildirin, 3) adapter buraxın, 4) post-mortem, linterləri yeniləyin.

D. Açar/sert kompromasiyası

1. Revoke/rotate, 2) vebhukları yenidən oynamaq, 3) audit, 4) tərəfdaşları xəbərdar etmək.

E. Təkrarların/dublların partlaması

1. Idempotency-Key/TTL yoxlayın, 2) dedupu gücləndirin, 3) «səs-küylü» mənbəyi məhdudlaşdırın.

16) Giriş çek siyahısı

1. Müqavilələri təsvir edin (OpenAPI/AsyncAPI/IDL), linterlər və CI daxil edin.
2. auth (OAuth2/OIDC, mTLS), vebhuk imzaları, açar rotasiyasını konfiqurasiya edin.
3. / QoS/limitləri, ağır-query-guard və backpressure daxil edin.
4. Müşahidə səviyyəsini artırın: SLI/SLO, treklər, daşbordlar, alertlər.
5. Relizləri təşkil edin: canary/blue-green, schema-first miqrasiya.
6. Versiya/hadisə/açar kataloqunu və deprekeyt proseslərini işə salın.
7. Chaos/perf/security testləri aparın, playbukları tərtib edin.
8. Məlumatların minimuma endirilməsini və tənzimləyiciyə uyğunluğunu mütəmadi olaraq yoxlayın.

17) Lüğət

Contract-first - koddan əvvəl formal müqavilələr vasitəsilə API layihələndirilməsi.
Idempotency-Key - əməliyyatın təkrarlanmasını təhlükəsiz edən açardır.
AsyncAPI - hadisə interfeyslərinin spesifikasiyası.
QoS - keyfiyyət/prioritet xidmət sinfi.
DLQ - problemli mesajlar üçün «ölü növbə».
Error budget burn - SLO ilə bağlı səhvlərin büdcəsini «yandırma» sürəti.

Nəticə: Ekosistemin API-ləri end-point dəsti deyil, müqavilə, təhlükəsizlik, kvota və müşahidə sistemidir. Bu çərçivəni izləyən ekosistem sürətli inteqrasiyalar, proqnozlaşdırıla bilən SLO və downtime olmadan təhlükəsiz təkamül əldə edir - şəbəkə səviyyəsindən və identifikasiyadan hadisə axınlarına və hesabatlara qədər.