API pentru ecosistem

(Secțiunea: Ecosistem și rețea)

1) Obiective și principii

• Integrare rapidă, previzibilă (↓ de integrare).
• Fiabilitate și scalabilitate (SLO, QoS, backpressure).
• Siguranță și conformitate (drepturi minime, audit).
• Evoluție fără defecțiuni (versiuni, compatibilitate, ficheflags).

Principii: contract-first, minimizarea datelor, idempotenta, observabilitate-implicit, „doua viteze” ale versiunilor (core vs experimental).

2) taxonomie API

1. REST/HTTP - operațiuni CRUD/comandă sincronă, cheie de idempotență, paginare/cursoare.
2. gRPC/QUIC - latență scăzută, fluxuri, protocoale binare.
3. Evenimente (Pub/Sub) - evenimente de domeniu ('depozit. „,” plata. „,” pod. „,” risc. ').
4. Webhooks - notificări inverse cu semnături și retroactive.
5. GraphQL (limitat) - agregarea citește peste storefronturi materializate.
6. Admin/Meta - directoare, versiuni, stări, chei, cote.

Niveluri de acces: Public (metode limitate/lectură), Partener (scopuri și cote), Intern (contururi private).

3) Contracte și scheme

OpenAPI/AsyncAPI/Protobuf IDL este o singură sursă de adevăr.
Contracte de date - teste de compatibilitate, lintere de circuit, interzicerea „ruperii” câmpurilor fără MAJOR.
Cataloage: active/rețele, PSP/metode, regiuni/jurisdicții, versiuni SDK, steaguri de capacitate.

Contract MINIM REST (fragment 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 }

Evenimente (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) Versioning și compatibilitate

SemVer: "MAJOR. MINOR. PATCH ". MINOR/PATCH - compatibil înapoi; MAJOR - versiuni paralele ('/v1 ', '/v2') + adaptoare.
Politica de respingere: fereastră ≥ 90 de zile, „două linii” de sprijin, notificări automate pentru contracte.
Feature Flags: activați/dezactivați câmpurile/metodele după regiune/partener.
Negocierea capacității: declararea profilurilor acceptate la strângerea mâinilor.

5) Idempotence, ordine și cursoare

Idempotency-Key pentru comenzi (creare/anulare), tastele TTL ≥ 72 ore.
Semantica exact o dată prin outbox/inbox și consumator idempotent.
Paginare de cursoare: 'next _ cursor', rezistență la inserții/ștergeri.
Sortarea și filtrele sunt stabile, clar documentate.

6) Securitate și încredere

mTLS (service↔service), pinning de serturi și rotație cheie.
OAuth2/OIDC (acreditări client, JWT cu scurt TTL), PoP/DPoP pentru legarea la canal.
Semnături Webhook (NMAS/versiune cheie/timp), protecție repetiție.
RBAC/ABAC și PoLP: scopuri, org_id/tenant_id, limite de obiect/funcționare.
Minimizarea DLP/PII: interzicerea PII în etichete/jurnale, tokenizarea identificatorilor.
Rate-limite și WAF: pe org/rută/regiune, protecție împotriva abuzurilor.

Politica cheie de probă (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) Cote, QoS și backpressure

Clasele QoS: P0 (plăți/punte/finalizare), P1 (produs), P2 (vrac/arhivă).
Cote/limite: SPR, concur-requests, bytes/sec, subject/party for events.
Controlul admiterii: respingerea timpurie a cererilor „scumpe”, garda de interogare grea.
Backpressure: jetoane/credite, cozi cu DLQ, retraiuri cu jitter.

Politica de cote

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

8) Observabilitate: SLI/SLO, valori, urme

• p95/99 latență по маршрутам, Rata de succes, Bugetul de eroare arde, Coadă-lag p95, Prospețime webhooks, Succes de livrare%.
• Conformitatea contractului% (scheme/semnături).
• Webhook reîncercare/scădere%.

SLO: P0 p95 ≤ 400 ms, Disponibilitate ≥ 99. 95%; Livrare webhook p95 ≤ 2 с; Evenimente prospețime p95 ≤ 60 с.

Valori: histograme de latență, coduri de eroare, dimensiunea răspunsurilor, SPR, per chiriaș.
Urme: end-to-end 'trace _ id' (edge→gateway→service→DB→event/webhook).
Jurnale: structurat, fără PII, corelație prin 'request _ id'.

9) Downtime-free modele de lansare

Albastru-verde/canar cu porți SLO și exterior-ejectare.
Schema-prima evoluție: doar adăugarea de câmpuri, adaptoare pentru clienții vechi.
Zero-downtime migrații de baze de date: DDL online, convertoare bidirecționale.
Controlul schimbării: timelock, registru de audit și compatibilitate.

10) Cataloage și registre

Înregistrare API/versiune

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

Catalog de evenimente

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

Taste/scopuri

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

11) Testarea și respectarea contractelor

Contracte-teste: generarea de clienți, validarea schemelor, negative-_cases.
Teste de evenimente replay: rezistență la repetare/reordonare.
Haos/Lat-teste: pierdere/injecții jitter, stor lent.
Teste de securitate: semnături webhook, rotație cheie, reluarea atacurilor.
Profile de performanță: vârfuri SLA, rute fierbinți, punte DA/dependență.

12) Exemple de interfețe

Carti web (semnatura si retrai)

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 (Agregarea Citește, Citește Numai)

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

gRPC (fluxul de evenimente)

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

13) Procese și roluri

Proprietar API - Contract/Versiune/SLO/Cota.
Securitate - chei/semnături/audit/DLP.
SRE/Ops - tablouri de bord, alerte, capacitate.
Partener Succes - onboarding, limite, phicheflags.
Conformitate - jurisdicții, sancțiuni, raportare.

14) Tablouri de bord

API de bază: latență/eroare/RPS pe rută și cort.
Webhooks: livrare p95, retries, picături, semnături.
Evenimente: prospețime, decalaj, sănătatea consumatorilor, DLQ.
Securitate: chei de expirare, semnături, cereri refuzate.
Guvernanță: versiuni active/depreciate, compatibilitatea contractelor.

15) Incidente Playbook

A. Creșterea latenței p95 P0

1. Activați P0 și prioritatea P2-throttle; 2) gateway-uri de scară;

2. Comutați o parte a citirilor la memoria cache 4) analiza rutelor „fierbinți”.

B. Livrare webhook drop

1. Verificați semnăturile/ora de schimb, 2) crește retroys/timeout,

2. activați loturile, 4) treceți temporar la punctul final al glonțului.

C. Contracte în derivă

1. Activați "modul strict',

2. anunțați producătorul, 3) eliberați adaptorul, 4) post-mortem, actualizați linterele.

D. Compromisul cheie/cert

1. Revocare/rotire, 2) reluare webhooks, 3) audit, 4) notifica partenerii.

E. Repetare/Explozie

1. Verificați Idempotency-Key/TTL, 2) consolidarea deadup, 3) limita sursa „zgomotos”.

16) Lista de verificare a implementării

1. Descrieți contractele (OpenAPI/AsyncAPI/IDL), includeți lintere și CI.
2. Configurați auth (OAuth2/OIDC, mTLS), semnături webhook, rotație cheie.
3. Introduceți cote/QoS/limite, heavy-query-guard și backpressure.
4. Ridicați observabilitatea: SLI/SLO, piese, tablouri de bord, alerte.
5. Organizați versiuni: canar/albastru-verde, schema-primele migrații.
6. Porniți directorul versiune/eveniment/cheie și depreciați procesele.
7. Efectuați teste de haos/perf/securitate, aranjați cărți de joc.
8. Revizuiți în mod regulat minimizarea datelor și conformitatea cu reglementările.

17) Glosar

Primul contract - proiectarea API prin contracte formale la cod.
Idempotency-Key - o cheie care face operația repetată în condiții de siguranță.
AsyncAPI - specificarea interfețelor de evenimente.
QoS - Calitatea serviciului/Clasa prioritară.
DLQ - „coadă moartă” pentru mesajele cu probleme.
Eroare de buget arde - rata de „ardere” a bugetului de eroare în raport cu SLO.

Concluzie: API-ul ecosistemului nu este un set de puncte finale, ci un sistem gestionat de contracte, securitate, cote și observabilitate. Urmând acest cadru, ecosistemul câștigă integrări rapide, SLO-uri previzibile și evoluție sigură fără timpi morți - de la nivelul rețelei și autentificare la fluxurile de evenimente și raportare.