API dell'ecosistema

(Sezione Ecosistema e Rete)

1) Obiettivi e principi

• Integrazioni rapide e prevedibili (time-to-integration).
• Affidabilità e scalabilità (SLO, QoS, backpressure).
• Sicurezza e regolazione (diritti minimi, verifiche).
• Evoluzione senza interruzioni (versioni, compatibilità, phicheflagi).

Principi: contract-first, minimizzazione dei dati, idampotenza, osservabilità-by-default, due velocità di rilascio (core vs experimental).

2) Tassonomia API

1. REST/HTTP - CRUD/comandi sincronizzati, idempotency-key, pagination/cursors.
2. gRPC/QUIC - bassa latitanza, strim, protocolli binari.
3. Events (Pub/Sub) - Eventi di dominio ('deposit', 'payout', 'bridge', 'risk').
4. Webhooks - Notifiche inverse con firme e retrai.
5. GraphQL (limitatamente) - letture di aggregazione sopra le vetrine materializzate.
6. Ammin/Meta - cartelle, versioni, stati, chiavi, quote.

Livelli di accesso: Public (metodi/letture limitate), Partner (scoop e quote), Internal (tracciati privati).

3) Contratti e schemi

L'IDL è un'unica fonte di verità.
Data Contracts - Test di compatibilità, diagrammi di lenti, disattivazione dei campi di rottura senza MAJOR.
Cataloghi: risorse/reti, metodi PSP, regioni/giurisdizioni, versioni SDK, bandiere delle funzionalità.

Contratto REST minimo (frammento 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 }

Eventi (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 e compatibilità

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH - Posteriori MAJOR - versioni parallele ('/v1 ', '/v2') + adattatori.
Deprecation policy: una finestra da 90 giorni, due linee di supporto, notifiche automatiche dei contratti.
Feature Flags: attivazione/disattivazione dei campi/metodi per regione/partner.
Capability Negotion - Annuncia profili supportati durante la stretta di mano.

5) Idampotenza, ordine e cursori

Idempotency-Key per comandi (create/cancel), TTL chiavi da 72 ore

Exactly-once semantica attraverso outbox/inbox e la consumatrice idompotente.
La paginazione con i puntatori è «next _ cursor», resistente alle inserzioni/rimozioni.
I filtri e i filtri sono stabili, chiaramente documentati.

6) Sicurezza e fiducia

mTLS (service↔service), pinning dei sarti e rotazione delle chiavi.
OAUTh2/OIDC (client credentials, JWT con TTL breve), PoP/DPoP per il collegamento al canale.
Etichette Webhook (NMAS/versione chiave/ora), protezione da ripetizioni.
RBAC/ABAC e PoLP: scorci, org _ id/tenant _ id, limiti per oggetto/operazione.
DLP/PII-Minimizzazione: proibizione del PII nelle etichette o nelle etichette, tornizzazione degli identificatori.
Rate-limits e WAF: per org/route/region, protezione da abuse.

Criteri chiave di esempio (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) Quote, QoS e backpressure

Classi QoS: P0 (pagamenti/ponte/finalizzazione), P1 (prodotti alimentari), P2 (bulk/archivio).
Quote/limiti: RPS, concur-richiesti, byties/sec, tema/partitella per gli eventi.
Deviazione precoce delle query «costose», heavy-query-guard.
Backpressure: token/prestiti, code con DLQ, retrai con jitter.

Criteri per le quote

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

8) Osservabilità: SLI/SLO, metriche, tracciabili

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

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

Metriche: istogrammi di latenza, codici di errore, dimensioni delle risposte, RPS, per-tenant.
Trade: passante «trace _ id» (edge→gateway→service→DB→event/webhook).
I loghi sono strutturati, senza PII, correlati su «sollest _ id».

9) Cartelli di rilascio senza downtime

Blue-Green/Canary con SLO-gate e outlier-ejection.
Schema-first evoluzione: solo aggiunta di campi, adattatori per i clienti più vecchi.
Zero-downtime migrazioni database: DDL online, convertitori bidirezionali.
Controllo delle modifiche: timelock, controllo e registro di compatibilità.

10) Cartelle e registri

Registro API/versioni

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

Directory eventi

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

Chiavi/scorciatoie

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

11) Test e conformità dei contratti

Contract-test: generazione di client, convalida di diagrammi, negative- _ case.
Test eventi replay - Resistenza a ripetute/riordinamento.
Chaos/Lat-test - iniezioni di perdita/jitter, store lento.
Sicurezza-test: firme di webhook, rotazione delle chiavi, attacchi di ripetizione.
Profili performance: spiagge SLA, percorsi hot, DA/ponte dipendenza.

12) Esempi di interfaccia

Webhooks (firma e 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 (lettura aggregativa, sola lettura)

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

gRPC (flusso di eventi)

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

13) Processi e ruoli

API Owner - contratto/versione/SLO/quote.
Sicurezza - chiavi/firme/controllo/DLP.
SRE/Ops - dashboard, alert, capacity.
Partner Success - onboarding, limiti, ficcoflagi.
Compliance - giurisdizione, sanzioni, rapporti.

14) Dashboard

Core API latency/error/RPS per percorsi e tendenti.
Webhooks: delivery p95, retries, drops, firme.
Events: freshness, lag, consumer health, DLQ.
Sicurezza: chiavi di scadenza, firme, richieste rifiutate.
Governance: versioni attive/deprecati, compatibilità dei contratti.

15) Playbook incidenti

A. Crescita p95 latitanza P0

1. Includi la priorità P0 e P2-throttle; 2) ridimensionare i gateway

2. Passare alla cache alcune letture 4) Analisi delle rotte calde.

B. Calo delivery webhook

1. Controlla le firme/spostamento orario, 2) aumenta i ritai/timeout,

2. attivare batch, 4) passare temporaneamente al pool endpoint.

Contratti C. Drivt

1. Abilita «strict mode» (ritaglia messaggi non corretti),

2. notifica il produttore, 3) rilascia l'adattatore, 4) post mortem, aggiorna i linter.

D. Compromissione della chiave/serto

1. Revoke/rotate, 2) ricalcolare webhoop, 3) controllo, 4) informare i partner.

E. Esplosione di ripetizioni/riprese

1. Controlla Idempotency-Key/TTL, 2) rinforza deadup, 3) limita sorgente «rumorosa».

16) Assegno-foglio di implementazione

1. Descrivere i contratti (OpenAPI/AsyncAPI/IDL), includere i linter e gli ICI.
2. Configura auth (OAuth2/OIDC, mTLS), firma web, rotazione delle chiavi.
3. Immettere quote/QoS/limiti, heavy-query-guard e backpressure.
4. Aumentare l'osservabilità: SLI/SLO, piste, dashboard, alert.
5. Organizzare le release: canary/blue-green, schema-first migration.
6. Esegui la directory di versioni/eventi/chiavi e i processi di deprecazione.
7. Esegui chaos/perf/security test, esegui playbook.
8. Ridimensionare regolarmente i dati e la regolazione.

17) Glossario

Contract-first - Progettazione API tramite contratti formali prima del codice.
Idempotency-Key è una chiave che rende l'operazione di ripetizione sicura.
AsyncAPI - Specifica le interfacce di evento.
QoS è una classe di qualità/priorità di servizio.
DLQ - Coda morta per messaggi problematici.
Errore budget burn - Velocità di «bruciare» il budget degli errori relativi a SLO.

L'API dell'ecosistema non è un insieme di endpoint, ma un sistema gestito di contratti, sicurezza, quote e osservabilità. Seguendo questo framework, l'ecosistema ottiene rapidamente integrazioni, SLO prevedibili e un'evoluzione sicura senza downtime, dal livello di rete all'autenticazione ai flussi di eventi e ai report.