Als das Produktteam von Deka Technology DekaFlow — unsere B2B-Workflow-Automatisierungsplattform — konzipierte, war die erste Architekturentscheidung auch die folgenreichste: ein API-First-Design-Ansatz von Beginn an. In Enterprise-Umgebungen zeigt sich schnell, was passiert, wenn APIs nachträglich eingebaut werden. Integrations-Schulden häufen sich schneller an als technische Schulden, und DACH-Unternehmenskunden zahlen dafür mit verzögerten Go-Lives und fragilen Verbindungen.
Was API-First wirklich bedeutet
API-First bedeutet nicht einfach "eine API schreiben." Es bedeutet, dass der API-Vertrag entworfen, geprüft und vereinbart wird, bevor eine einzige Zeile Implementierungscode geschrieben wird. Für DekaFlow hieß das: zuerst eine OpenAPI-3.1-Spezifikation erstellen — mit vollständiger Definition aller Endpunkte, Schemata, Fehlercodes und Beispiel-Payloads — und diese Spezifikation einem Designreview durch unsere Architekten, das Produktteam und ausgewählte Zielkunden zu unterziehen.
Der Vorteil zeigt sich sofort: Frontend-Entwickler, Backend-Entwickler und externe Integrationspartner können parallel gegen den Vertrag arbeiten, unterstützt durch Mock-Server, die direkt aus der Spezifikation generiert werden. Bei DekaFlow reduzierte dieser parallele Workflow die Integrationszeit im Vergleich zum traditionellen sequentiellen Ansatz erheblich.
Versionierungsstrategie: Warum wir URL-basierte Versionierung gewählt haben
Drei Versionierungsstrategien dominieren das API-Design: URL-basiert (/v1/, /v2/), Header-basiert (Accept: application/vnd.deka.v2+json) und Query-Parameter-basiert. Für Enterprise-B2B-Kunden empfehlen wir konsequent URL-basierte Versionierung und setzen sie in DekaFlow aus drei Gründen ein:
- Sichtbarkeit: Operations-Teams und API-Gateways können per URL routen, ohne Header zu inspizieren.
- Cachefähigkeit: CDN- und Proxy-Schichten cachen
/v1/und/v2/unabhängig voneinander, ohne benutzerdefinierte Vary-Header. - Eindeutigkeit: Enterprise-Beschaffungs- und Audit-Teams können exakte Endpunkt-Versionen dokumentieren, die in SLAs referenziert werden.
DekaFlow pflegt gleichzeitig zwei aktive Hauptversionen, mit einer 12-monatigen Abkündigungs-Vorankündigung und automatisierten Deprecation-Warnungen im Entwicklerportal.
Rate-Limiting-Design für B2B-Verkehrsmuster
Consumer-APIs drosseln pro Nutzer. B2B-APIs drosseln pro Tenant, pro Ressourcentier und pro Endpunkt-Familie — die Muster unterscheiden sich grundlegend. DekaFlow implementiert einen Token-Bucket-Algorithmus mit drei Dimensionen: Burst-Allowance auf Tenant-Ebene, nachhaltiger Durchsatz pro Endpunkt und ein globales Sicherheitsventil zum Schutz des Clusters unter Kaskadenlast. Clients erhalten X-RateLimit-Remaining- und Retry-After-Header in jeder Antwort, und Kontingent-Dashboards werden im Entwicklerportal in Echtzeit angezeigt.
Authentifizierung: OAuth2 für menschliche Flows, API-Keys für Machine-to-Machine
DekaFlow unterstützt beide Authentifizierungsmuster. Menschliche Nutzer authentifizieren sich über den OAuth2 Authorization Code Flow mit PKCE, integriert in die bestehenden Identity-Provider der Kunden (Entra ID, Okta und On-Premise-LDAP via SAML-Bridge). Machine-to-Machine-Integrationen — ERP-Konnektoren, Datenpipelines, automatisiertes Provisioning — verwenden bereichsbegrenzte API-Keys mit konfigurierbarem Ablauf und Rotationserinnerungen.
Die zuverlässigste Enterprise-Integration ist eine, bei der jedes Credential-Rotationsereignis automatisiert, auditiert und ohne Downtime abläuft. Die Key-Management-API von DekaFlow ermöglicht Kunden die programmatische Rotation von Zugangsdaten ohne manuelle Portal-Eingriffe.
SDK-Generierung und das Entwicklerportal
Aus einer einzigen OpenAPI-Spezifikation generieren wir typisierte SDKs für TypeScript, Python und Java mit Deka-eigenen Templates, die konsistentes Fehlerhandling und Retry-Logik durchsetzen. Das DekaFlow-Entwicklerportal — auf Basis von Stoplight Elements — rendert interaktive Dokumentation, stellt eine Sandbox-Umgebung mit deterministischen Test-Fixtures bereit und verlinkt direkt auf den Changelog jeder API-Version. Ingenieure tragen via Pull Requests zur Spezifikation bei; das Portal aktualisiert sich bei jedem Merge automatisch.
Das Ergebnis ist eine API-Plattform, auf die Enterprise-B2B-Kunden in Tagen statt Wochen onboarden können — und die die Realität langfristiger DACH-Enterprise-Verträge übersteht, in denen Integrationspartner wechseln, ERP-Versionen aktualisiert werden und sich Compliance-Anforderungen weiterentwickeln.
Diesen Leitfaden für die nächste interne Prüfung nutzen
Offene Entscheidungen, Nachweisverantwortliche und Prüftermine sollten vor der Wahl eines Umsetzungswegs festgehalten werden.