API-Entwicklung · Integration · Betrieb
APIs und Schnittstellen für Unternehmenssysteme entwickeln
Wenn Systeme heute über Dateiexporte und Handarbeit sprechen, entwerfen und bauen wir die Schnittstelle, die sie verlässlich verbindet: erst der Vertrag, dann der Code, am Ende Dokumentation und Monitoring.
- REST, gRPC, GraphQL, Kafka
- OAuth 2.0 und OpenID Connect
- OpenAPI-Vertrag vor der Implementierung
01Ausgangslage
Woran Sie merken, dass eine Schnittstelle fehlt
Meist beginnt es mit einem Dateiexport, der nachts läuft und morgens fehlt. Ob einzelne Schnittstelle oder Teil einer größeren individuellen Softwareentwicklung: Diese vier Lagen sind der typische Anlass.
-
Datenaustausch per Datei und Handarbeit
Zwei oder mehr Systeme tauschen Daten über Dateiexporte, Datenbankzugriffe oder Handarbeit aus, und das ist fehleranfällig.
-
Partner brauchen eine stabile Schnittstelle
Eine Anwendung soll Partnern oder Kunden eine stabile, dokumentierte Schnittstelle bieten.
-
Der Monolith wird zerlegt
Die Teile brauchen klar definierte Verträge, siehe Cloud-native Entwicklung.
-
Die Altanwendung soll weiterleben
Sie bleibt hinter einer modernen Schnittstelle nutzbar, siehe Anwendungsmodernisierung.
02Entscheidungsmatrix
REST, gRPC, GraphQL oder Kafka: die Anforderung entscheidet
Es gibt keinen besten Typ. Das ist unsere Ausgangsposition; aus der Praxis folgt meist eine Mischung: REST nach außen, gRPC oder Ereignisse im Inneren.
| Typ | Stärke | Passt für | Vorsicht bei |
|---|---|---|---|
| REST mit JSON, beschrieben in OpenAPI | breit verstanden, einfach zu testen und zu dokumentieren, gutes Werkzeug-Ökosystem | externe und partnerseitige Schnittstellen, CRUD-nahe Fachfunktionen | stark verschachtelte Abfragen, Streaming |
| gRPC | strikt typisierter Vertrag, effizient, Streaming | interne Dienst-zu-Dienst-Kommunikation mit hohen Anforderungen an Leistung und Typsicherheit | direkte Nutzung aus Browsern und durch Partner ohne gRPC-Erfahrung |
| GraphQL | Clients wählen Felder selbst, ein Endpunkt für viele Sichten | Oberflächen mit wechselnden Datenbedarfen über mehrere Quellen | Berechtigungen je Feld, Abfragekomplexität und Caching müssen bewusst gelöst werden |
| Kafka (Ereignisströme) | Entkopplung, Wiederabspielbarkeit, hohe Durchsatzraten | Ereignisse zwischen Systemen, Integrationen mit mehreren Empfängern | Fragen, die eine sofortige Antwort erfordern; Aufwand für Betrieb und Schema-Pflege |
03Anti-Muster
Drei Entwürfe, die später teuer werden
Manche Schnittstellen sind von Anfang an falsch geschnitten. Diese Muster vermeiden wir, auch wenn sie kurzfristig der schnellste Weg scheinen.
- Schnittstellen, die interne Datenbankstrukturen 1:1 nach außen reichen
- Integration über direkten Datenbankzugriff auf Drittsysteme
- Ein Ereignisstrom für Abläufe, die eigentlich eine synchrone Antwort benötigen
04Vorgehen
API-Vertrag zuerst: von den Anforderungen bis zum Monitoring
Der Vertrag ist das Artefakt, das Sie prüfen und freigeben. Konsumenten können gegen Mock-Antworten arbeiten, bevor die Implementierung steht.
05Checkliste
Zehn Punkte, die im API-Vertrag stehen, bevor Code entsteht
Bevor Implementierung beginnt, legen wir diese Punkte fest.
- Zweck und Konsumenten. Wer ruft auf, mit welchen Anforderungen an Verfügbarkeit und Latenz? Diese Angaben liefern Sie, wir helfen beim Formulieren.
- Ressourcen und Operationen. Benennung, Pfade, Methoden; Idempotenz für Schreiboperationen, die bei Wiederholung nicht doppelt wirken dürfen.
- Datenmodell und Validierung. Typen, Pflichtfelder, Formate; Eingaben werden an der Grenze validiert.
- Fehlerformat. Einheitlich, maschinenlesbar; für HTTP-Schnittstellen bietet sich RFC 9457 (Problem Details for HTTP APIs) an.
- Authentifizierung und Autorisierung. Verfahren, Rollen und Berechtigungen je Operation.
- Paginierung, Filter, Sortierung für Listen; Obergrenzen für Antwortgrößen.
- Begrenzung der Nutzung. Ratenbegrenzung und Kontingente je Konsument.
- Versionierung und Änderungsregeln. Was ist abwärtskompatibel, wie werden Änderungen angekündigt, wie lange laufen alte Versionen.
- Testbarkeit. Beispielanfragen und -antworten, Vertragstests gegen die Beschreibung.
- Betrieb. Welche Kennzahlen, Protokolle und Alarme gehören zur Schnittstelle.
06Sicherheit
OAuth 2.0, OpenID Connect und vier Risiken, die wir zuerst schließen
Für Autorisierung zwischen Anwendungen und Nutzern setzen wir OAuth 2.0 und OpenID Connect ein, mit den aktuellen Sicherheitsempfehlungen aus RFC 9700 (Best Current Practice for OAuth 2.0 Security). Die Absicherung orientiert sich an den OWASP API Security Top 10 (2023): Besonders häufig und folgenreich sind diese vier Risiken.
| OWASP-Risiko | Was in jeder Operation gilt |
|---|---|
| API1: fehlende Prüfung der Berechtigung auf Objekt-Ebene | Jede Operation prüft die Berechtigung serverseitig am konkreten Objekt. |
| API5: fehlende Prüfung auf Funktionsebene | Die Berechtigung wird je Operation geprüft; Antworten enthalten nur die benötigten Felder. |
| API4: uneingeschränkter Ressourcenverbrauch | Ratenbegrenzung, Kontingente je Konsument und Obergrenzen für Antwortgrößen. |
| API9: mangelnde Inventarisierung von Schnittstellen | Alle Schnittstellen sind inventarisiert. |
Zugangsgeheimnisse liegen nicht im Code; Ablage und Rotation klären wir mit Ihrem Sicherheitskonzept (IAM und Zero Trust).
07Bestandssysteme
Altsysteme hinter einer eigenen Schicht kapseln
Bestandssysteme bringen eigene Grenzen mit: begrenzte Schnittstellen, feste Formate, langsame Antworten. Wir kapseln sie hinter einer eigenen Schicht, die Übersetzung, Zeitüberschreitungen, Wiederholung mit Begrenzung und eine definierte Fehlerbehandlung übernimmt, statt deren Eigenheiten an die Konsumenten weiterzugeben.
Bei asynchroner Integration planen wir doppelte Zustellung (Idempotenz auf Empfängerseite) und die Behandlung nicht verarbeitbarer Nachrichten ein.
08Betrieb
Dokumentation und Monitoring gehören zur Schnittstelle
-
Dokumentation
OpenAPI-Beschreibung als Quelle, daraus Referenz und Beispiele; Änderungsprotokoll; Betriebsanleitung für Ihr Team.
-
Monitoring
Anfrage-, Fehler- und Latenzkennzahlen je Operation, Protokollierung mit Korrelations-ID, Alarme nach vereinbarten Schwellen; Ausrichtung an OpenTelemetry für Traces, Metriken und Logs. Zum Betrieb siehe Monitoring und Observability.
09Ablauf
Sechs Schritte vom Systeminventar bis zur laufenden Schnittstelle
- 01
Aufnahme
Systeme, Konsumenten, Datenflüsse, Sicherheitsvorgaben.
- 02
Vertragsentwurf
OpenAPI-Beschreibung bzw. Ereignisschema, Fehler- und Versionierungsregeln.
- 03
Implementierung
Mit Code-Review und automatisierten Tests, darunter Vertragstests.
- 04
Absicherung
Authentifizierung, Autorisierung, Begrenzung, Sicherheitsprüfungen in der Pipeline.
- 05
Betriebsbereitschaft
Dokumentation, Monitoring, Bereitstellung auf Ihrer Plattform (Kubernetes oder bestehende Umgebung).
- 06
Abnahme
API-Beschreibung, Betriebsanleitung und Einweisung Ihres Teams; Sie nehmen gegen den freigegebenen Vertrag ab.
Freigegeben wird der Vertrag, nicht der Code
Bevor Code entsteht, prüfen Sie die API-Beschreibung. Was dort steht, wird implementiert und in der Pipeline gegen die Beschreibung getestet.
10Abgrenzung
Eigene Schnittstelle oder fertiger Konnektor?
Das spricht für SKAFFON
- Die beteiligten Systeme sind benannt und der Zweck der Schnittstelle steht fest.
- Es braucht Softwareentwicklung, nicht nur Konfiguration eines Integrations-Werkzeugs.
Das spricht dagegen
- Ein Standardprodukt oder ein vorhandener Konnektor deckt die Integration ab.
- Sie suchen ein reines Integrations-Werkzeug ohne Softwareentwicklung (iPaaS-Konfiguration).
- Die beteiligten Systeme sind noch nicht benannt und der Zweck ist offen; dann beginnt ein Scoping, kein Entwicklungsauftrag.
11
Was Sie zum Start mitbringen und woraus sich das Angebot ergibt
Mitbringen sollten Sie fachliche Ansprechpartner, Zugang zu den anzubindenden Systemen und deren Dokumentation, Angaben zu erwarteter Last und Verfügbarkeit sowie Sicherheits- und Datenschutzvorgaben.
Nach einem Erstgespräch erhalten Sie ein Angebot mit abgegrenztem Umfang.
12
Häufige Fragen
Welcher Schnittstellentyp passt zu uns?
Das hängt von den Anforderungen ab. REST mit OpenAPI eignet sich für externe und partnerseitige Schnittstellen, gRPC für interne Dienst-zu-Dienst-Kommunikation, GraphQL für Oberflächen mit wechselnden Datenbedarfen und Kafka für Ereignisse zwischen Systemen. Meist ergibt sich eine Mischung.
Wie sichern Sie eine Schnittstelle ab?
Mit OAuth 2.0 und OpenID Connect nach den aktuellen Empfehlungen aus RFC 9700 und mit Orientierung an den OWASP API Security Top 10. Jede Operation prüft die Berechtigung serverseitig am konkreten Objekt.
Was passiert mit Systemen, die nur begrenzte Schnittstellen haben?
Wir kapseln sie hinter einer eigenen Schicht für Übersetzung, Zeitüberschreitungen, begrenzte Wiederholung und definierte Fehlerbehandlung.
Was bekommen wir am Ende?
Eine laufende, getestete Schnittstelle mit freigegebener API-Beschreibung, Betriebsanleitung und Einweisung Ihres Teams.
13
Wo die Schnittstelle sonst noch hineinspielt
-
Individualsoftware
Die Schnittstelle als Teil einer größeren Entwicklung.
-
Cloud-native Entwicklung
Verträge zwischen den Teilen eines zerlegten Monolithen.
-
Anwendungsmodernisierung
Altanwendungen hinter moderner Schnittstelle weiter nutzen.
-
IAM und Zero Trust
Ablage und Rotation von Zugangsgeheimnissen.
Welche Systeme sollen miteinander sprechen?
Schicken Sie uns die Liste der beteiligten Systeme. Wir antworten mit einem Vorschlag für den Vertragsentwurf.