API des Ökosystems

(Abschnitt: Ökosystem und Netzwerk)

1) Ziele und Grundsätze

• Schnelle, vorhersehbare Integration (Time-to-Integration ↓)
• Zuverlässigkeit und Skalierbarkeit (SLO, QoS, Backpress).
• Sicherheit und Einhaltung der Vorschriften (Mindestrechte, Audit).
• Evolution ohne Pannen (Versionen, Kompatibilität, Ficheflags).

Prinzipien: contract-first, Datenminimierung, Idempotenz, observability-by-default, „two speed“ releases (core vs experimental).

2) API-Taxonomie

1. REST/HTTP - synchrone CRUD/Befehlsoperationen, idempotency-key, pagination/cursors.
2. gRPC/QUIC - niedrige Latenz, Streams, binäre Protokolle.
3. Ereignisse (Pub/Sub) - Domänenereignisse („Einzahlung“, „Auszahlung“, „Brücke“, „Risiko“).
4. Webhooks - Rückbenachrichtigungen mit Signaturen und Retrays.
5. GraphQL (eingeschränkt) - Aggregierte Lesungen über materialisierte Vitrinen.
6. Admin/Meta - Verzeichnisse, Versionen, Status, Schlüssel, Kontingente.

Zugriffsebenen: Öffentlich (eingeschränkte Methoden/Lesen), Partner (Scopes und Quoten), Intern (private Konturen).

3) Verträge und Regelungen

OpenAPI/AsyncAPI/Protobuf IDL ist eine einzige Quelle der Wahrheit.
Datenkontrakte - Kompatibilitätstests, Schaltungslinter, Verbot von „Breaking“ -Feldern ohne MAJOR.
Verzeichnisse: Assets/Netzwerke, PSP/Methoden, Regionen/Jurisdiktionen, SDK-Versionen, Fähigkeitsflags.

Minimaler REST-Vertrag (OpenAPI-Fragment)

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 }

Ereignisse (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) Versionierung und Kompatibilität

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH - rückwärtskompatibel; MAJOR - parallele Versionen ('/v1', '/v2') + Adapter.
Deprection policy: Fenster ≥ 90 Tage, „zwei Zeilen“ Support, automatische Benachrichtigungen über Verträge.
Feature Flags: Aktivieren/Deaktivieren von Feldern/Methoden nach Region/Partner.
Capability Negotiation: Deklariert unterstützte Profile beim Händeschütteln.

5) Idempotenz, Ordnungen und Cursor

Idempotency-Key für Befehle (create/cancel), TTL-Schlüssel ≥ 72 Stunden

Exactly-once Semantik durch outbox/inbox und idempotent consumer.
Paginierung mit Cursor: 'next _ cursor', Widerstand gegen Einfügungen/Löschungen.
Sortierungen und Filter sind stabil, explizit dokumentiert.

6) Sicherheit und Vertrauen

mTLS (service↔service), Sert-Pinning und Schlüsselrotation.
OAuth2/OIDC (Client-Credentials, JWT mit kurzer TTL), PoP/DPoP zum Binden an den Kanal.
Webhook Signaturen (NMAS/Schlüsselversion/Zeit), Wiederholungsschutz.
RBAC/ABAC und PoLP: Scopes, org_id/tenant_id, Objekt-/Operationslimits.
DLP/PII-Minimierung: Verbot von PII in Labels/Logs, Tokenisierung von IDs.
Rate-limits und WAF: per org/route/region, Schutz vor Missbrauch.

Beispielschlüsselrichtlinie (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) Quoten, QoS und Backpressure

QoS-Klassen: P0 (Auszahlungen/Bridge/Finalisierung), P1 (Produkt), P2 (Masse/Archiv).
Quoten/Limits: RPS, concur-requests, bytes/sec, theme/party for events.
Admission control: frühe Ablehnung von „teuren“ Anfragen, heavy-query-guard.
Backpressure: Token/Credits, Warteschlangen mit DLQ, Retrays mit Jitter.

Kontingentrichtlinie

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

8) Beobachtbarkeit: SLI/SLO, Metriken, Traces

• p95/99 latency по маршрутам, Success Rate, Error budget burn, Queue-lag p95, Freshness webhooks, Delivery success%.
• Vertragskonformität% (Schemas/Signaturen).
• Webhook retry/dropped%.

SLO (Benchmarks): P0 p95 ≤ 400 ms, Verfügbarkeit ≥ 99. 95%; Webhook delivery p95 ≤ 2 с; Events freshness p95 ≤ 60 с.

Metriken: Latenzhistogramme, Fehlercodes, Antwortgröße, RPS, per-tenant.
Traces: Ende-zu-Ende' trace _ id'(edge→gateway→service→DB→event/webhook).
Logs: strukturiert, ohne PII, Korrelation durch 'request _ id'.

9) Veröffentlichungsmuster ohne Downtime

Blau-Grün/Canary mit SLO-Gates und Outlier-Ejection.
Schema-erste Entwicklung: nur Hinzufügen von Feldern, Adapter für alte Kunden.
Zero-Downtime der DB-Migration: Online-DDL, bidirektionale Konverter.
Änderungskontrolle: Timelock, Audit und Kompatibilitätsregister.

10) Kataloge und Register

API/Versionsregistrierung

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

Ereigniskatalog

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

Schlüssel/Skopes

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

11) Prüfung und Einhaltung von Verträgen

Vertragstests: Kundengenerierung, Validierung von Schemata, negative-_cases.
Replay-Tests von Ereignissen: Resistenz gegen Wiederholungen/Nachbestellungen.
Chaos/Lat-Tests: Verlust-/Jitter-Injektionen, langsamer Stor.
Sicherheitstests: Webhook-Signaturen, Schlüsselrotation, Wiederholungsangriffe.
Leistungsprofile: SLA-Adhäsionen, „heiße“ Routen, DA/Abhängigkeitsbrücke.

12) Beispiele für Schnittstellen

Webhooks (Signatur und Retrays)

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 (Aggregationslesungen, schreibgeschützt)

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

gRPC (Ereignisablauf)

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

13) Prozesse und Rollen

API Owner - Vertrag/Version/SLO/Quote.
Sicherheit - Schlüssel/Signaturen/Audit/DLP.
SRE/Ops - Dashboards, Alerts, Kapazität.
Partner Erfolg - Onboarding, Limits, Ficheflags.
Compliance - Jurisdiktionen, Sanktionen, Berichterstattung.

14) Dashboards

Kern-API: Latenz/Fehler/RPS nach Routen und Zelten.
Webhooks: Lieferung p95, Retries, Drops, Unterschriften.
Events: freshness, lag, consumer health, DLQ.
Sicherheit: Schlüssel zum Ablauf, Signaturen, verweigerte Anfragen.
Governance: aktive Versionen/Deprecates, Kompatibilität der Verträge.

15) Playbook der Vorfälle

A. Anstieg der p95-Latenz von P0

1. Aktivieren Sie die Priorität P0 und P2-throttle; 2) Skalieren der Gateways;

2. Umschalten eines Teils der Lesungen auf den Cache; 4) Analyse der „heißen“ Routen.

B. Drop Delivery Webhook

1. Überprüfen Sie Signaturen/Stundenverschiebung, 2) erhöhen Sie Retrays/Timeouts,

2. Batchi aktivieren, 4) vorübergehend zu einem Pull-Endpoint wechseln.

C. Drift Verträge

1. Aktivieren Sie „strict mode“ (schneiden Sie falsche Nachrichten ab),

2. benachrichtigen Sie den Hersteller, 3) lassen Sie den Adapter, 4) post-mortem, aktualisieren Sie die linters.

D. Kompromittierung des Schlüssels/Serts

1. Revoke/rotate, 2) Webhooks neu spielen, 3) auditieren, 4) Partner benachrichtigen.

E. Explosion von Wiederholungen/Takes

1. Überprüfen Sie den Idempotency-Key/TTL, 2) verstärken Sie den Dedup, 3) begrenzen Sie die „laute“ Quelle.

16) Checkliste Umsetzung

1. Beschreiben Sie Verträge (OpenAPI/AsyncAPI/IDL), aktivieren Sie Linter und CIs.
2. Konfigurieren Sie auth (OAuth2/OIDC, mTLS), Webhook-Signaturen, Schlüsselrotation.
3. Kontingente/QoS/Limits, Heavy-Query-Guard und Backpressure eingeben.
4. Erhöhung der Beobachtbarkeit: SLI/SLO, Tracks, Dashboards, Alerts.
5. Organisieren Sie Releases: canary/blue-green, schema-first migration.
6. Versions-/Ereignis-/Schlüsselverzeichnis und Deprecate-Prozesse starten.
7. Chaos/perf/Sicherheitstests durchführen, Playbooks gestalten.
8. Datenminimierung und Compliance regelmäßig revidieren.

17) Glossar

Contract-first - API-Design durch formale Verträge vor dem Code.
Der Idempotency-Key ist der Schlüssel, der die Wiederholung einer Operation sicher macht.
AsyncAPI - Spezifikation von Ereignisschnittstellen.
QoS ist die Dienstqualitäts-/Prioritätsklasse.
DLQ ist eine „tote Warteschlange“ für problematische Nachrichten.
Error budget burn - Geschwindigkeit des „Brennens“ des Fehlerbudgets relativ zum SLO.

Fazit: Die Ökosystem-API ist keine Sammlung von Endpunkten, sondern ein verwaltetes System aus Verträgen, Sicherheit, Quoten und Beobachtbarkeit. Nach diesem Framework erhält das Ökosystem schnelle Integrationen, vorhersehbare SLOs und eine sichere Downtime-freie Evolution - von der Netzwerkschicht und Authentifizierung bis hin zu Ereignisströmen und Berichterstattung.