L'API de l'écosystème

(Section : Écosystème et réseau)

1) Objectifs et principes

• Intégrations rapides et prévisibles (time-to-integration ↓).
• Fiabilité et évolutivité (SLO, QoS, backpressure).
• Sécurité et respect de la réglementation (droits minimums, audit).
• Évolution sans pannes (versions, compatibilité, ficheflagi).

Principes : contract-first, minimisation des données, idempotence, observabilité-par-défaut, « deux vitesses » des versions (core vs experimental).

2) Taxonomie API

1. REST/HTTP - Opérations CRUD/commande synchrones, idempotency-key, pagination/cursors.
2. gRPC/QUIC - faible latence, strimes, protocoles binaires.
3. Events (Pub/Sub) est un événement de domaine (« deposit. », « payout. », « bridge. », « risk. »).
4. Webhooks - notifications inversées avec signatures et retraits.
5. GraphQL (limité) est une lecture agrégante sur les vitrines matérialisées.
6. Admin/Meta - répertoires, versions, statuts, clés, quotas.

Niveaux d'accès : Public (méthodes limitées/lecture), Partner (scoops et quotas), Internal (circuits privés).

3) Contrats et régimes

OpenAPI/AsyncAPI/Protobuf IDL est une source unique de vérité.
Les contrats de données sont des tests de compatibilité, des liens de schéma, l'interdiction des champs « cassés » sans MAJOR.
Catalogues : actifs/réseaux, PSP/méthodes, régions/juridictions, versions SDK, indicateurs de capacité.

Contrat REST minimum (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 }

Événements (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 et compatibilité

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH - rétrocompatibles ; MAJOR - versions parallèles ('/v1 ', '/v2') + adaptateurs.
Politique de déprécation : fenêtre ≥ 90 jours, « deux lignes » de soutien, notifications automatiques pour les contrats.
Feature Flags : Activer/désactiver les champs/méthodes par région/partenaire.
Negotiation capability : annonce des profils pris en charge en cas de poignée de main.

5) Idempotence, ordres et curseurs

Idempotency-Key pour les commandes (create/cancel), TTL des clés ≥ 72 h.
Exactly-once sémantique via outbox/inbox et consumer idempotent.
Pagination par les curseurs : 'next _ cursor', résistance aux inserts/suppressions.
Tri et filtres - stable, clairement documenté.

6) Sécurité et confiance

mTLS (service↔service), pinning de serts et rotation de clés.
OAuth2/OIDC (client credentials, JWT avec un court TTL), PoP/DPoP pour la liaison au canal.
Signatures Webhook (NMAS/version clé/temps), protection contre les répétitions.
RBAC/ABAC et PoLP : scoops, org_id/tenant_id, limites par installation/opération.
DLP/PII-minimisation : interdiction des PII dans les labels/logs, tokenisation des identifiants.
Rate-limits et WAF : per org/route/region, protection contre l'abuse.

Exemple de stratégie de clé (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) Quotas, QoS et backpressure

Classes QoS : P0 (paiements/pont/finalisation), P1 (produits), P2 (bulk/archives).
Quotas/limites : RPS, concur-requests, bytes/sec, thème/lot pour les événements.
Contrôle d'admission : rejet précoce des demandes « chères », heavy-query-guard.
Backpressure : jetons/crédits, files d'attente avec DLQ, retraits avec jitter.

Politique de quotas

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

8) Observabilité : SLI/SLO, métriques, traces

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

SLO (repères) : P0 p95 ≤ 400 ms, Disponibilité ≥ 99. 95%; Webhook delivery p95 ≤ 2 с; Events freshness p95 ≤ 60 с.

Métriques : histogrammes de latence, codes d'erreur, taille des réponses, RPS, per-tenant.
Tracés : "trace _ id' (edge→gateway→service→DB→event/webhook).
Logs : structuré, sans PII, corrélation par "request _ id'.

9) Patterns de libération sans downtime

Blue-Green/Canary avec des jeux SLO et outler-ejection.
Schema-first evolution : uniquement l'ajout de champs, adaptateurs pour les anciens clients.
Migration DB zero-downtime : DDL en ligne, convertisseurs bidirectionnels.
Contrôle des modifications : timelock, audit et registre de compatibilité.

10) Catalogues et registres

Registre des API/versions

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

Répertoire des événements

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

Clés/Clés

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

11) Test et conformité contractuelle

Contrats-tests : génération de clients, validation de schémas, negative-_cases.
Tests de replay d'événements : résistance aux répétitions/réorganisation.
Chaos/Lat-tests : injections de perte/jitter, store lent.
Tests de sécurité : signatures de webhooks, rotation des clés, attaques de répétition.
Profils de performance : Épices SLA, itinéraires « chauds », DA/pont de dépendance.

12) Exemples d'interfaces

Webhooks (signature et 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 (lecture agrégante, lecture seule)

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

gRPC (flux d'événements)

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

13) Processus et rôles

API Owner - contrat/version/SLO/quotas.
Sécurité - clés/signatures/audit/DLP.
SRE/Ops - dashboards, alertes, capacity.
Partner Success - onbording, limites, ficheflags.
Conformité - juridictions, sanctions, rapports.

14) Dashboards

API core : latency/error/RPS par itinéraire et tentants.
Webhooks : livraison p95, retries, drops, signatures.
Events: freshness, lag, consumer health, DLQ.
Sécurité : clés d'expiration, signatures, demandes refusées.
Governance : versions actives/dépréciations, compatibilité contractuelle.

15) Playbook des incidents

A. Croissance de la latence p95 P0

1. Activer la priorité P0 et P2-throttle ; 2) mettre à l'échelle les passerelles ;

2. Commuter une partie des lectures en cache ; 4) analyse des itinéraires « chauds ».

B. Chute du webhook de livraison

1. Vérifier les signatures/décalage horaire, 2) augmenter les retraits/délais,

2. allumer batchi, 4) passer temporairement à pull-endpoint.

C. Drift Contrats

1. Activer « mode strict » (couper les messages incorrects),

2. aviser le producteur, 3) libérer l'adaptateur, 4) post-mortem, mettre à jour les linters.

D. Compromission de la clé/serta

1. Revoke/rotate, 2) reconfigurer les webhooks, 3) audit, 4) aviser les partenaires.

E. Explosion des répétitions/prises

1. Vérifier Idempotency-Key/TTL, 2) renforcer le dedup, 3) limiter la source « bruyante ».

16) Chèque de mise en œuvre

1. Décrire les contrats (OpenAPI/AsyncAPI/IDL), inclure les linters et CI.
2. Configurer auth (OAuth2/OIDC, mTLS), les signatures Web, la rotation des clés.
3. Entrez les quotas/QoS/limites, heavy-query-guard et backpressure.
4. Augmenter l'observabilité : SLI/SLO, pistes, dashboards, alertes.
5. Organiser les sorties : canary/blue-green, schema-first migration.
6. Démarrer le répertoire des versions/événements/clés et les processus de déprécation.
7. Effectuer des tests chaos/perf/security, organiser des playbooks.
8. Revivez régulièrement la minimisation des données et la conformité à la réglementation.

17) Glossaire

Contrat-first - conception de l'API via des contrats formels avant le code.
Idempotency-Key est une clé qui sécurise la répétition de l'opération.
AsyncAPI est une spécification d'interface d'événement.
QoS est une classe de qualité/priorité de service.
DLQ est la « file d'attente morte » pour les messages problématiques.
Error budget burn est le taux de « brûler » le budget des erreurs par rapport à SLO.

Résultat : L'API de l'écosystème n'est pas un ensemble d'endpoints, mais un système géré de contrats, de sécurité, de quotas et d'observabilité. En suivant ce cadre, l'écosystème obtient des intégrations rapides, des SLO prévisibles et une évolution sûre sans downtime - de la couche réseau à l'authentification, en passant par les flux d'événements et les rapports.