--- title: "APIs und Schnittstellen entwickeln | SKAFFON" description: "API-Entwicklung für Unternehmenssysteme: REST, gRPC, GraphQL und Kafka im Vergleich, OpenAPI-Verträge, OAuth2/OIDC, Dokumentation und Monitoring." url: https://skaffon.de/software/api-schnittstellen/ --- ![Aufgeklappter Laptop mit Entwicklungsumgebung und Quellcode auf dunklem Tisch, seitlich in pinkes und blaues Licht getaucht](/_astro/aufgeklappter-laptop-entwicklungsumgebung-quellcode.dNS0LzjL_Z1beagm.jpg) 1. [Startseite](/) 2. [Software](/software/) 3. APIs und Schnittstellen für Unternehmenssysteme entwickeln 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. [Projekt anfragen](/projekt-anfragen/) [Zur Entscheidungsmatrix](/software/api-schnittstellen/#rest-grpc-graphql-oder-kafka-die-anforderung-entscheidet) - REST, gRPC, GraphQL, Kafka - OAuth 2.0 und OpenID Connect - OpenAPI-Vertrag vor der Implementierung Autor: [Ibrahim Yesilay](/unternehmen/ibrahim-yesilay/), Gründer und Geschäftsführer Stand: 13.11.2026 Ausgangslage ## 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](/software/individualsoftware/): 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](/software/cloud-native-entwicklung/) Die Teile brauchen klar definierte Verträge, siehe [Cloud-native Entwicklung](/software/cloud-native-entwicklung/). - ### [Die Altanwendung soll weiterleben](/software/application-modernisierung/) Sie bleibt hinter einer modernen Schnittstelle nutzbar, siehe [Anwendungsmodernisierung](/software/application-modernisierung/). Entscheidungsmatrix ## 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. __Schnittstellentypen im Vergleich: Stärke, Einsatzfeld und Vorsicht__ | Typ | Stärke | Passt für | Vorsicht bei | | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | **REST** mit JSON, beschrieben in [OpenAPI](https://spec.openapis.org/oas/latest.html) | 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 | Anti-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 ![Nahaufnahme von farbig hervorgehobenem Quellcode in einem Texteditor mit dunklem Hintergrund, Zeilennummern am linken Rand](/_astro/farbig-hervorgehobenem-quellcode-texteditor.DG0_R6G9_Z22JIx.jpg) Vorgehen ## 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. Checkliste ## 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)](https://www.rfc-editor.org/rfc/rfc9457) 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. Sicherheit ## 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)](https://www.rfc-editor.org/rfc/rfc9700). Die Absicherung orientiert sich an den [OWASP API Security Top 10 (2023)](https://api-security.owasp.org/editions/2023/en/0x11-t10): Besonders häufig und folgenreich sind diese vier Risiken. __OWASP-API-Risiken und die Gegenmaßnahme in jeder Operation__ | 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](/cybersecurity/iam-zero-trust/)). Bestandssysteme ## 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. ![Nahaufnahme eines optischen SFP-Transceiver-Moduls mit Anschlusskabel vor weiteren Steckmodulen in einem Regal](/_astro/optischen-sfp-transceiver-moduls.BNfbScAc_1fq1Nf.jpg) Betrieb ## Dokumentation und Monitoring gehören zur Schnittstelle - ### Dokumentation OpenAPI-Beschreibung als Quelle, daraus Referenz und Beispiele; Änderungsprotokoll; Betriebsanleitung für Ihr Team. - ### [Monitoring](/managed-services/observability-monitoring/) Anfrage-, Fehler- und Latenzkennzahlen je Operation, Protokollierung mit Korrelations-ID, Alarme nach vereinbarten Schwellen; Ausrichtung an [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) für Traces, Metriken und Logs. Zum Betrieb siehe [Monitoring und Observability](/managed-services/observability-monitoring/). Ablauf ## Sechs Schritte vom Systeminventar bis zur laufenden Schnittstelle 1. 01 ### Aufnahme Systeme, Konsumenten, Datenflüsse, Sicherheitsvorgaben. 2. 02 ### Vertragsentwurf OpenAPI-Beschreibung bzw. Ereignisschema, Fehler- und Versionierungsregeln. 3. 03 ### Implementierung Mit Code-Review und automatisierten Tests, darunter Vertragstests. 4. 04 ### Absicherung Authentifizierung, Autorisierung, Begrenzung, Sicherheitsprüfungen in der Pipeline. 5. 05 ### Betriebsbereitschaft Dokumentation, Monitoring, Bereitstellung auf Ihrer Plattform ([Kubernetes](/leistungen/kubernetes-beratung/) oder bestehende Umgebung). 6. 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. Abgrenzung ## 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. ## 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. Was den Aufwand bestimmt Zahl und Qualität der anzubindenden Systeme, Komplexität der Fachlogik, Anforderungen an Verfügbarkeit und Sicherheit, Umfang von Dokumentation und Tests sowie der gewünschte Betriebsanteil. ## 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. ## Wo die Schnittstelle sonst noch hineinspielt - ### [Individualsoftware](/software/individualsoftware/) Die Schnittstelle als Teil einer größeren Entwicklung. Weiter - ### [Cloud-native Entwicklung](/software/cloud-native-entwicklung/) Verträge zwischen den Teilen eines zerlegten Monolithen. Weiter - ### [Anwendungsmodernisierung](/software/application-modernisierung/) Altanwendungen hinter moderner Schnittstelle weiter nutzen. Weiter - ### [IAM und Zero Trust](/cybersecurity/iam-zero-trust/) Ablage und Rotation von Zugangsgeheimnissen. Weiter ## Welche Systeme sollen miteinander sprechen? Schicken Sie uns die Liste der beteiligten Systeme. Wir antworten mit einem Vorschlag für den Vertragsentwurf. [Projekt anfragen](/projekt-anfragen/) [Alle Software-Leistungen](/software/)