Экосистемаи API

(Қисмат: Экосистема ва шабака)

1) Ҳадафҳо ва принсипҳо

• Интегратсияи зуд, пешгӯишаванда (вақт ба ҳамгироӣ ↓).
• Эътимоднокӣ ва миқёспазирӣ (SLO, QOS, backpressure).
• Бехатарӣ ва мутобиқат (ҳуқуқҳои ҳадди ақал, аудит).
• Таҳаввулот бидуни тақсимот (версияҳо, мутобиқат, ficheflags).

Принсипҳо: аввал-шартнома, кам кардани маълумот, номутобиқатӣ, мушоҳида бо нобаёнӣ, "ду суръат" -и релизҳо (аслӣ против таҷрибавӣ).

2) Таксономияи API

1. REST/HTTP - амалиётҳои ҳамоҳангшудаи CRUD/фармон, idempotency-key, pagination/cursors.
2. GRPC/QUIC - таъхири кам, ҷараёнҳо, протоколҳои бинарӣ.
3. Ҳодисаҳо (Pub/Sub) - рӯйдодҳои домейн ('амонат. ',' пардохт. ',' пул. ',' хатар. ').
4. Webhooks - огоҳиномаҳои баръакс бо имзоҳо ва бозхонд.
5. GraphQL (маҳдуд) - ҷамъбасти мағозаҳо аз мағозаҳои моддӣ хонда мешавад.
6. Admin/Meta - феҳристҳо, версияҳо, статусҳо, калидҳо, квотаҳо.

Сатҳи дастрасӣ: Ҷамъиятӣ (усулҳои маҳдуд/хониш), Шарик (миқёс ва квотаҳо), дохилӣ (контурҳои хусусӣ).

3) Шартномаҳо ва нақшаҳо

Open-API/Async-API/Protobuf IDL манбаи ягонаи ҳақиқат аст.
Шартномаҳои маълумот - санҷишҳои мутобиқат, линтерҳои ноҳиявӣ, манъи майдонҳои "шикастан" бидуни MAJOR.
Каталогҳо: дороиҳо/шабакаҳо, PSP/усулҳо, минтақаҳо/қаламравҳо, версияҳои SDK, парчамҳои қобилият.

Шартномаи ҳадди аққали REST (порчаи Open

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 }

Ҳодисаҳо (Async .API)

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 - ақиб-мувофиқ; MAJOR - версияҳои параллелӣ ('/v1 ', '/v2') + адаптерҳо.
Сиёсати радкунӣ: равзана ≥ 90 рӯз, "ду хат" -и дастгирӣ, огоҳиномаҳои автоматӣ барои шартномаҳо.
Парчамҳои хусусият: фаъол/ғайрифаъол кардани майдонҳо/усулҳо аз рӯи минтақа/шарик.
Музокирот оид ба қобилият: эълон кардани профилҳои дастгиришаванда ҳангоми ларзондани даст.

5) Idempotence, фармонҳо ва курсорҳо

Калиди Idempotency барои фармонҳо (эҷод/бекор кардан), калидҳои TTL ≥ 72 соат.
Маҳз як маротиба семантика тавассути outbox/паёмдони қуттӣ ва истеъмолкунандаи idempotent.
Пагинатсия аз ҷониби курсорҳо: 'next _ cursor', муқовимат ба воридкунӣ/несткунӣ.
Навъбандӣ ва филтрҳо устувор, равшан ҳуҷҷатгузорӣ шудаанд.

6) Амният ва эътимод

MTLS (service↔service), печонидани сертҳо ва гардиши калидҳо.
OAuth2/OIDC (эътимодномаи муштарӣ, JWT бо TTL кӯтоҳ), POP/DP барои пайвастшавӣ ба канал.
Имзоҳои Webhook (NMAS/версияи калидӣ/вақт), муҳофизати такрорӣ.
RBAC/ABAC ва POLP: миқёс, org_id/tenant_id, маҳдудиятҳои объект/амалиёт.
Кам кардани DLP/PII: манъи PII дар тамғакоғазҳо/гузоришҳо, токенизатсияи идентификаторҳо.
Меъёрҳо ва WAF: барои org/масир/минтақа, ҳифзи сӯиистифода.

Намунаи сиёсати калидӣ (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 (яклухт/бойгонӣ).
Квотаҳо/маҳдудиятҳо: RPS, дархостҳои ризоият, байтҳо/сек, мавзӯъ/ҳизб барои чорабиниҳо.
Назорати қабул: пеш аз мӯҳлат рад кардани дархостҳои "гарон", посбонони вазнин.
Backpressure: токенҳо/кредитҳо, навбатҳо бо DLQ, бо 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 po marshrutam, Меъёри муваффақият, Сӯхтани буҷаи хатогӣ, Queue-lag p95, webhooks тару тоза, Муваффақияти расонидани%.
• Мутобиқати шартнома% (схемаҳо/имзоҳо).
• Webhook retry/коҳиш%.

SLO: P0 p95 ≤ 400 ms, Дастрасӣ ≥ 99. 95%; Таҳвили Webhook p95 ≤ 2 с; Ҳодисаҳои тару тоза p95 ≤ 60 с.

Нишондиҳандаҳо: гистограммаҳои таъхирнопазир, рамзҳои хатогӣ, андозаи ҷавобҳо, RPS, ҳар як иҷорагир.
Нишонаҳо: ба-охири 'trace _ id' (канори → дарвоза → хидмат → DB → ҳодиса/webhook).
Гузоришҳо: бидуни PII, таносуби аз ҷониби 'request _ id' сохташуда.

9) Намунаҳои озодкунии бебозгашт

Кабуд-Сабз/Канария бо дарвозаҳои SLO ва берунӣ.
Таҳаввулоти аввалини схема: танҳо илова кардани майдонҳо, адаптерҳо барои муштариёни кӯҳна.
Муҳоҷирати пойгоҳи додаҳои сифрӣ: DDL онлайн, табдилдиҳандагони дуҷониба.
Назорати тағирот: сабти вақт, аудит ва сабти мутобиқат.

10) Каталогҳо ва регистрҳо

Феҳристи API/Version

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) Санҷиш ва риояи шартномаҳо

Озмоишҳои шартномавӣ: тавлиди муштарӣ, санҷиши схема, negative-_cases.
Такрори санҷишҳои ҳодиса: муқовимат ба такрор/фармоиш.
Санҷишҳои хаос/лат-лат: тазриқи талафот/ҷиттер, стори суст.
Санҷишҳои амниятӣ: имзоҳои webhook, гардиши калидҳо, ҳамлаҳои такрорӣ.
Профилҳои иҷро: хӯшаҳои SLA, хатсайрҳои гарм, DA/купруки вобастагӣ.

12) Намунаҳои интерфейсҳо

Вебхукҳо (имзо ва ретрай)

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 - Шартнома/Версия/SLO/Квота.
Амният - калидҳо/имзоҳо/аудит/DLP.
SRE/Ops - панели панелҳо, огоҳиҳо, иқтидор.
Муваффақияти шарик - дар киштӣ, маҳдудиятҳо, phicheflags.
Мувофиқат - қаламравҳо, таҳримот, гузоришдиҳӣ.

14) Панели панелҳо

API-и асосӣ: ниҳонӣ/хато/RPS аз рӯи масир ва хайма.
Webhooks: расонидани p95, такрорӣ, қатраҳо, имзоҳо.
Чорабиниҳо: тару тоза, ақибмонӣ, саломатии истеъмолкунандагон, DLQ.
Амният: калидҳои мӯҳлат, имзоҳо, дархостҳои радшуда.
Идоракунӣ: версияҳои фаъол/амортизатсия, мутобиқати шартнома.

15) Ҳодисаҳои дафтарча

A. афзоиши p95 таъхири P0

1. Даргиронидани афзалияти P0 ва P2-throttle; 2) дарвозаҳои миқёсӣ;

2. Гузариш ба қисми хониш ба кэш 4) таҳлили хатсайрҳои "гарм".

B. тарки webhook таҳвил

1. Санҷидани имзоҳо/сменаи соат, 2) зиёд кардани бозсозӣ/танаффус,

2. партияҳоро фурӯзон кунед, 4) муваққатан ба нуқтаи охири тир гузаред.

Шартномаҳои C. Drift

1. Даргиронидани "ҳолати қатъӣ",

2. ба истеҳсолкунанда хабар диҳед, 3) адаптерро озод кунед, 4) пас аз марг, линтерҳоро нав кунед.

D. созишномаи калидӣ/сертификатсия

1. Бозхонд/гардиш, 2) такрори вебхукҳо, 3) аудит, 4) огоҳ кардани шарикон.

E. такрор кунед/таркиш кунед

1. Санҷиши Idempotency-Key/TTL, 2) маргро мустаҳкам кунед, 3) манбаи "ғавғо" -ро маҳдуд кунед.

16) Рӯйхати санҷиши амалисозӣ

1. Шартномаҳоро тавсиф кунед (Open

2. Танзимоти auth (OAuth2/OIDC, mTLS), имзоҳои webhook, гардиши калидҳо.
3. Ворид намудани квотаҳо/QOS/маҳдудиятҳо, пурборкунандаи посбон ва бозсозӣ.
4. Баланд бардоштани мушоҳида: SLI/SLO, роҳҳо, панелҳо, огоҳиҳо.
5. Варақаҳоро ташкил кунед: канарӣ/кабуд-сабз, муҳоҷирати схема-аввал.
6. Оғоз кардани феҳристи версия/ҳодиса/калид ва фарсудашавии равандҳо.
7. Санҷишҳои бетартибӣ/perf/амниятро гузаронед, китобҳои бозиро тартиб диҳед.
8. Мунтазам кам кардани маълумот ва риояи қонунро таҷдиди назар кунед.

17) Луғат

Шартнома-аввал - тарҳи API тавассути шартномаҳои расмӣ ба рамз.
Idempotency-Key - калидест, ки амалиётро бехатар такрор мекунад.
АсинкАПИ - мушаххасоти интерфейси ҳодисаҳо.
QOS - Сифати хизматрасонӣ/Синфи афзалиятнок.
DLQ - "навбати мурда" барои паёмҳои мушкилӣ.
Сӯзондани буҷаи хатогӣ - меъёри "сӯзондан" -и буҷаи хатогӣ нисбат ба SLO.

Сатри поён: экосистемаи API маҷмӯи нуқтаҳои ниҳоӣ нест, балки системаи идоракунии шартномаҳо, амният, квотаҳо ва мушоҳидаҳо мебошад. Бо пайравӣ аз ин чаҳорчӯба, экосистема интегратсияи босуръат, SLO-ҳои пешгӯишаванда ва таҳаввулоти бехатарро бидуни таъхир - аз қабати шабака ва аутентификатсия то ҷараён ва гузоришдиҳӣ ба даст меорад.