Schnittstellen dokumentieren: OpenAPI statt Wissen im Kopf

Die OpenAPI-Spezifikation legt fest, wie eine HTTP-Schnittstelle in einem maschinenlesbaren Dokument beschrieben wird. Ein Konsument soll den entfernten Dienst damit verstehen und mit wenig eigener Logik ansprechen können (OpenAPI-Spezifikation). Die aktuelle Fassung trägt die Nummer 3.2.1 und ist auf den 10. September 2026 datiert (OpenAPI-Spezifikation). Sie gehört zur Reihe 3.2, deren erste Fassung 3.2.0 vom 19. September 2025 stammt (OpenAPI-Spezifikation). Patch-Versionen wie 3.2.1 beheben Fehler im Dokument oder präzisieren Formulierungen, ändern aber nicht den Funktionsumfang der Reihe (OpenAPI-Spezifikation).

Technisch ist eine OpenAPI-Beschreibung ein JSON-Objekt, das wahlweise als JSON oder YAML geschrieben wird (OpenAPI-Spezifikation). Datenstrukturen beschreibt das Schema-Objekt; es ist standardmäßig eine Obermenge von JSON Schema in der Fassung Draft 2020-12 (OpenAPI-Spezifikation). Für Schnittstellen, bei denen das ERP oder ein Zahlungsdienst von sich aus Nachrichten schickt, gibt es das Feld webhooks: Es beschreibt eingehende Aufrufe, die der Konsument der API umsetzen kann (OpenAPI-Spezifikation). Eine Beschreibung erfasst damit beide Richtungen eines Datenflusses, nicht nur die Endpunkte, die der Shop selbst aufruft. Wann sich Push und wann sich Abfragen lohnen, vergleicht der Beitrag zu Webhooks und Polling.

Eine Grenze nennt die OpenAPI Initiative selbst: OpenAPI kann nicht jede denkbare HTTP-Schnittstelle beschreiben (OpenAPI Initiative). Wer zuerst programmiert und später beschreibt, stößt deshalb gelegentlich auf Konstruktionen, die sich nur verbogen abbilden lassen. Die Initiative empfiehlt, die Beschreibung zuerst zu schreiben und den Code daraus folgen zu lassen (OpenAPI Initiative). Bei einer neuen Anbindung ist das der einfachere Weg. Für bestehende Schnittstellen funktioniert er nicht mehr; dort hilft das Vorgehen weiter, das der Abschnitt zur nachträglichen Beschreibung zeigt.

Die Spezifikation verlangt nicht, jeden denkbaren Statuscode aufzuführen, weil nicht alle vorab bekannt sind. Erwartet wird aber, dass die Dokumentation die erfolgreiche Antwort und alle bekannten Fehler abdeckt (OpenAPI-Spezifikation). Für eine Auftragsschnittstelle sind das meist wenige, dafür folgenreiche Fälle. Entscheidend ist, dass die Beschreibung nicht nur den Code nennt, sondern auch die Reaktion, die der Client daraus ableiten soll. Sonst wiederholt die Middleware einen Auftrag, der längst gebucht ist, oder sie gibt einen Fall auf, der nach einer Minute Wartezeit durchgegangen wäre.

Für das Format der Fehlerantwort gibt es einen Standard: RFC 9457 definiert „Problem Details“, mit denen HTTP-APIs Fehler maschinenlesbar beschreiben, ohne eigene Fehlerformate erfinden zu müssen (RFC 9457). Eine Antwort trägt dann den Medientyp application/problem+json mit Feldern wie type, title, status und detail. In der OpenAPI-Beschreibung steht dieses Schema einmal unter components und wird an jede Fehlerantwort gehängt. Bei 429 kann der Server im Header Retry-After angeben, wie lange der Client warten soll (RFC 6585). Wie Wiederholungen, Warteschlangen und Benachrichtigungen dazu zusammenspielen, beschreibt der Beitrag zur Fehlerbehandlung in Schnittstellen; die Drosselung großer Importe behandelt der Beitrag zu Cloud-ERP-API-Limits.

Eine Beschreibung, die neben dem Code herläuft, veraltet. Die OpenAPI Initiative empfiehlt deshalb, Prüfwerkzeuge, die den Code gegen die Beschreibung abgleichen, in die Continuous Integration aufzunehmen; Abweichungen fallen dann umgehend auf, und die Beschreibung lässt sich ohne Sorge ändern (OpenAPI Initiative). Aus der Dokumentation wird so ein Vertrag zwischen Shop, Middleware und ERP: Was dort steht, gilt, und was davon abweicht, ist ein Fehler, egal auf welcher Seite.

Vertragstests prüfen, ob eine API ihren dokumentierten Vertrag weiterhin erfüllt. Der Beitrag zur API-Versionierung beschreibt sie als Schutz vor unbemerkten Breaking Changes. Wo sie laufen, ohne bei jedem Commit das echte ERP zu belasten, zeigt der Beitrag zu Testumgebungen für ERP-Schnittstellen. Für die Abnahme eines Projekts hat die Beschreibung einen weiteren Vorteil: Sie macht das Abnahmekriterium prüfbar. Statt „die Schnittstelle funktioniert“ steht im Protokoll, dass alle Antworten der Testläufe dem Schema entsprechen und jede beschriebene Fehlerantwort mindestens einmal ausgelöst wurde.

Ein Dienstleisterwechsel ist der Moment, in dem sich zeigt, ob eine Schnittstelle dokumentiert ist. Das BSI verlangt im IT-Grundschutz-Baustein zur Nutzung von Outsourcing mit der Anforderung OPS.2.3.A7, dass für geplante wie ungeplante Beendigungen Regelungen getroffen werden, einschließlich der Frage, wie Informationen und Daten zurückgegeben werden (BSI IT-Grundschutz). Für softwarenahe Dienstleistungen empfiehlt derselbe Baustein unter OPS.2.3.A21 Hinterlegungsverträge, die auch festlegen, wie häufig der Quellcode hinterlegt und dokumentiert wird (BSI IT-Grundschutz). Wer Entwicklung und Betrieb einer Schnittstelle an einen Dienstleister vergibt, kann diese Gedanken direkt übernehmen: Das Übergabepaket wird nicht am letzten Tag gepackt, sondern laufend gepflegt.

Rechtlich lohnt ein Blick auf die Nutzungsrechte. Schafft ein Arbeitnehmer ein Computerprogramm in Wahrnehmung seiner Aufgaben, ist nach § 69b UrhG ausschließlich der Arbeitgeber zur Ausübung aller vermögensrechtlichen Befugnisse berechtigt, sofern nichts anderes vereinbart ist (Urheberrechtsgesetz). Für einen externen Dienstleister trifft die Vorschrift keine solche Zuordnung. Welche Rechte an Code, Beschreibung, Testsammlung und Betriebshandbuch übergehen, sollte deshalb im Vertrag stehen, bevor der erste Endpunkt gebaut ist. Das ist eine organisatorische Empfehlung und ersetzt keine Rechtsberatung.

Für das kommende Jahr sprechen feste Termine dafür, die Beschreibung nicht auf „irgendwann“ zu verschieben. Für Umsätze ab dem 1. Januar 2027 endet für Unternehmen, deren Gesamtumsatz im Vorjahr mehr als 800.000 Euro betrug, die Übergangsregel, nach der sie Rechnungen an andere Unternehmen im Inland statt als E-Rechnung noch auf Papier oder in sonstigen elektronischen Formaten übermitteln dürfen; kleinere Unternehmen können sie bis Ende 2027 nutzen, für EDI-Verfahren gilt eine eigene Regel (Umsatzsteuergesetz). Wer dafür Rechnungsdaten aus Shop und ERP neu verbindet, ändert Schnittstellen. Der Beitrag zur E-Rechnungspflicht 2027 beschreibt die Datenwege; eine Beschreibung, die vorher steht, macht diese Änderung prüfbar.

Den richtigen Zeitpunkt bestimmt außerdem der Kalender des Handels. Während der Bestellspitze im November ruhen Arbeiten an Schnittstellen besser; der Beitrag zur Bestellspitze in der Black Week empfiehlt einen Änderungsstopp. Die Wochen danach eignen sich für Bestandsaufnahme und Beschreibung, damit die Dokumentation steht, bevor die Umstellungen des neuen Jahres beginnen. Im Budget gehört sie als eigene Zeile neben Entwicklung und Test; wie sich die übrigen Posten einer Anbindung zusammensetzen, steht im Beitrag zu den Kosten einer ERP-Anbindung.