Software30. März 2026Aktualisiert am 23. Oktober 20268 Min. LesezeitRedaktion Nano Concepts

REST-API mit OpenAPI: Design, Versio­nie­rung und Fehlerformat

Eine gute API ist verständlich, stabil und gut dokumentiert. So entwerfen Sie REST-APIs mit OpenAPI sauber, versionieren ohne Bruch und sparen mit klarer Fehlerkultur Integrationsaufwand.

Beitragsbild: REST-API mit OpenAPI: Design, Versionierung und Fehlerformat

Eine gute REST-API folgt fünf Regeln: Ressourcen statt Aktionen in der URL, eine gepflegte OpenAPI-Beschreibung als Vertrag, einheitliche Statuscodes und Fehlerformate, Versionierung mit Migrationsfenster statt Überraschung und automatisierte Prüfungen gegen die Spezifikation. Wer das früh festlegt, spart Integrationsaufwand, Supportanfragen und Ärger bei Updates.

Ob Onlineshop, CRM, mobile App oder Partnerportal: Moderne Software ist vernetzt, und die Qualität der Schnittstellen entscheidet darüber, wie reibungslos diese Vernetzung funktioniert. Dieser Beitrag führt durch Ressourcenmodell, OpenAPI, Konventionen, Fehlerbehandlung, Versionierung, Sicherheit und Tests – mit Tabellen, die sich als Checkliste für Ihre eigene API eignen.

Ressourcen statt Aktionen in URLs

REST denkt in Ressourcen, nicht in Funktionsaufrufen. Statt Endpunkten wie /getOrder oder /createOrder gibt es eine Ressource /orders, die über HTTP-Methoden angesprochen wird. Die Methoden haben festgelegte Eigenschaften, an denen sich Clients orientieren können:

Methode und BeispielZweckIdempotentTypische Antwort
GET /orders und GET /orders/{id}Liste oder einzelne Bestellung lesenja200
POST /ordersneue Bestellung anlegennein, außer mit Idempotency-Key201 mit Location-Header
PUT /orders/{id}Bestellung vollständig ersetzenja200 oder 204
PATCH /orders/{id}einzelne Felder ändernnicht garantiert200 oder 204
DELETE /orders/{id}Bestellung entfernen, sofern fachlich erlaubtja204

Diese Konsistenz macht eine API vorhersehbar: Wer einen Endpunkt verstanden hat, versteht auch die anderen. Verschachtelte Ressourcen wie /customers/{id}/orders sind sinnvoll, wenn die Beziehung fachlich eindeutig ist – zu tiefe Verschachtelungen machen eine API schwer lesbar. Ergänzen Sie einheitliche Regeln für Filter und Sortierung. Bei der Paginierung ist ein Cursor-Verfahren bei großen oder sich ändernden Datenmengen stabiler als Seitenzahlen, weil keine Einträge übersprungen oder doppelt geliefert werden, wenn zwischen zwei Abrufen Daten hinzukommen.

OpenAPI: der Vertrag zwischen den Systemen

Die OpenAPI-Spezifikation beschreibt eine REST-API maschinenlesbar: Endpunkte, Parameter, Datenschemata, Beispiele und mögliche Antworten. Sie ist damit Dokumentation und Vertrag zugleich. Aktuell verbreitet sind die Versionen 3.0 und 3.1; Version 3.1 nutzt JSON Schema für die Datenmodelle. Prüfen Sie vor der Wahl, welche Version Ihre Werkzeuge vollständig unterstützen.

Was eine gepflegte Spezifika­tion bringt

  • Entwickler sehen sofort, welche Felder erwartet und geliefert werden, und finden realistische Beispiele für Anfragen, Antworten und Fehlerfälle.
  • Aus der Spezifikation lassen sich Clients für verschiedene Programmiersprachen und interaktive Dokumentationen erzeugen.
  • Mock-Server, etwa mit Prism, ermöglichen es Frontend-Teams, parallel zu arbeiten, bevor das Backend fertig ist.
  • Linter wie Spectral prüfen den Styleguide automatisch, Werkzeuge wie oasdiff melden Breaking Changes in Pull Requests.
  • Auch KI-Anwendungen, die Ihre API als Werkzeug nutzen sollen, profitieren von einer präzisen Beschreibung mit klaren Feldnamen und Beispielen.

Design first oder Code first?

Beim Design-first-Ansatz wird die Spezifikation vor der Implementierung abgestimmt. Das lohnt sich besonders bei Partner-APIs, weil alle Beteiligten früh über dieselbe Grundlage sprechen. Beim Code-first-Ansatz entsteht die Spezifikation aus dem Code, was bei internen APIs oft schneller geht. In beiden Fällen gilt: Die Spezifikation gehört ins Repository, und eine Prüfung in der Pipeline stellt sicher, dass sie nicht vom tatsächlichen Verhalten abweicht.

Konventionen, die den Alltag erleichtern

Viele Probleme in Integrationsprojekten entstehen nicht durch komplexe Logik, sondern durch uneinheitliche Details. Legen Sie Konventionen früh fest und halten Sie sie in einem kurzen API-Styleguide fest:

  • Benennung: eine einheitliche Schreibweise für Felder, etwa camelCase oder snake_case, und Ressourcen im Plural.
  • Zeitangaben: konsequent nach ISO 8601 mit Zeitzone.
  • Beträge: nicht als Fließkommazahl, sondern als Ganzzahl der kleinsten Einheit oder als Zeichenkette, jeweils mit Währungscode.
  • Idempotenz: Wiederholte Anfragen dürfen keine doppelten Bestellungen erzeugen – etwa durch einen Idempotency-Key bei POST-Anfragen.
  • Paginierung: ein einheitliches Verfahren, inklusive Hinweis, ob weitere Daten folgen.
  • Strukturierte Felder: getrennte Felder statt zusammengesetzter Zeichenketten, die der Empfänger erst zerlegen muss.

Fehlerkultur: Statuscodes und Fehlerformat

Eine API zeigt ihre Qualität vor allem dann, wenn etwas schiefgeht. Klare Statuscodes sparen Support-Zeit, weil Entwickler sofort erkennen, wo das Problem liegt:

CodeBedeutungTypischer Einsatz
400ungültige Anfragefehlerhaftes JSON, fehlende Parameter
401nicht angemeldetToken fehlt oder ist abgelaufen
403nicht berechtigtgültige Anmeldung, aber keine Rechte
404nicht gefundenRessource existiert nicht oder ist nicht sichtbar
409Konfliktgleichzeitige Bearbeitung, doppelte Anlage
422nicht verarbeitbarformal korrekt, aber fachliche Validierung fehlgeschlagen
429zu viele AnfragenRate Limit erreicht, mit Retry-After-Header
503Dienst nicht verfügbarWartung oder Überlast, mit Retry-After-Header

Ebenso wichtig ist ein einheitliches Fehlerformat. Bewährt hat sich der Standard „Problem Details for HTTP APIs“ (RFC 9457) mit dem Medientyp application/problem+json und den Feldern type, title, status, detail und instance. Bei Validierungsfehlern ergänzen Sie eine Liste, welches Feld aus welchem Grund abgelehnt wurde. Der Fehlertyp sollte maschinenlesbar sein, damit Clients gezielt reagieren können; Stacktraces und interne Details gehören nicht in die Antwort. Vermeiden Sie vor allem, Fehler mit Status 200 und einer Meldung im Antworttext zu beantworten – das erschwert die automatische Fehlerbehandlung beim Client.

Versio­nie­rung ohne Bruch

APIs entwickeln sich weiter. Die meisten Änderungen lassen sich additiv umsetzen, ohne eine neue Version zu brauchen – vorausgesetzt, Clients ignorieren unbekannte Felder. Diese Regel sollten Sie in der Dokumentation ausdrücklich festhalten. Die Übersicht zeigt, was als Breaking Change gilt:

ÄnderungBreaking Change?
neues optionales Feld in der Antwortnein
neuer Endpunkt oder neuer optionaler Parameternein
Feld entfernen oder umbenennenja
Datentyp oder Format eines Feldes ändernja
neues Pflichtfeld in der Anfrageja
neuer Wert in einer Aufzählung (Enum)möglich, wenn Clients unbekannte Werte nicht tolerieren
Bedeutung oder Statuscode eines Verhaltens ändernja
Authentifizierungsverfahren ändernja

Für die Hauptversion gibt es mehrere Wege. Die Version im Pfad, etwa /v1/orders, ist leicht sichtbar, lässt sich einfach testen und cachen und hat sich bei Partner-APIs durchgesetzt. Die Version im Header oder Medientyp hält URLs stabil, ist aber aufwendiger zu dokumentieren und zu testen. Erhöhen Sie die Hauptversion nur bei Breaking Changes.

Entscheidend ist der Umgang mit Änderungen. Breaking Changes sollten nur mit einem Migrationsfenster erfolgen, dokumentiert im Changelog und angekündigt über Deprecation-Hinweise. Der Sunset-Header (RFC 8594) teilt Clients maschinenlesbar mit, ab wann eine Version abgeschaltet wird. Bei Partner-APIs planen wir typischerweise 90 bis 180 Tage Parallelbetrieb ein. Bei mobilen Apps sollten Sie länger rechnen, denn alte App-Versionen bleiben im Umlauf; hier helfen eine Mindestversion und ein sanfter Hinweis auf das Update. Protokollieren Sie, welche Clients welche Version nutzen, damit Sie wissen, wen Sie ansprechen müssen, bevor Sie abschalten.

Qualität und Schutz: Contract-Tests und Sicherheit

Contract-Tests prüfen, ob eine API die Erwartungen ihrer Konsumenten erfüllt. Mit Pact legen Konsumenten fest, welche Anfragen und Antworten sie erwarten, und das Backend wird bei jedem Deployment dagegen getestet. Ergänzend lassen sich Antworten automatisch gegen die OpenAPI-Beschreibung validieren und mit Werkzeugen wie Schemathesis aus der Spezifikation heraus mit vielen Eingaben prüfen. So fallen unbeabsichtigte Änderungen auf, bevor sie Partner treffen.

Zu jeder produktiven API gehören außerdem Schutzmaßnahmen. Für den Zugriff von Partnern und Servern hat sich OAuth 2.0 bewährt, bei Server-zu-Server-Zugriffen häufig mit Client-Credentials; API-Schlüssel sind nur mit klar begrenzten Rechten vertretbar. Das größte Risiko liegt oft in fehlender Autorisierung auf Objektebene: Prüfen Sie bei jeder Anfrage nicht nur, ob der Aufrufer angemeldet ist, sondern ob er auf genau diese Ressource zugreifen darf. Diese Schwachstelle führt die OWASP API Security Top 10 (Ausgabe 2023) an. Dazu kommen Rate Limiting, Eingabevalidierung anhand des Schemas und Logs, die Fehler nachvollziehbar machen, ohne sensible Daten zu speichern. Einen Überblick über typische Risiken bietet unsere OWASP-Web-Security-Checkliste.

Praxis­bei­spiel und Checkliste

Schnitt­stellen im Unternehmens­alltag

In vielen Projekten verbinden APIs bestehende Systeme miteinander – etwa ein Immobilien-CRM-Portal mit der Maklersoftware onOffice, einen Onlineshop mit dem ERP oder eine mobile App mit dem Backend. Angenommen, ein Händler stellt seinen Partnern eine Bestell-API bereit. Zwei Jahre später soll das Feld price in unitPrice und currency aufgeteilt werden. Der saubere Weg: Die neuen Felder erscheinen zusätzlich, price wird als veraltet gekennzeichnet und im Changelog angekündigt, ein Sunset-Datum liegt in ausreichendem Abstand. Die Protokolle zeigen, welche Partner price noch lesen, und diese werden gezielt angesprochen. Erst dann entfällt das alte Feld – in einer neuen Hauptversion, falls es Pflicht war. Wie solche Verbindungen geplant werden, lesen Sie im Beitrag ERP, CRM und Shop verbinden.

Auch zwischen den Diensten eines verteilten Systems sind solche Verträge unverzichtbar. Ob die Aufteilung in Services für Ihr Produkt überhaupt sinnvoll ist, klärt der Beitrag Microservices oder Monolith.

Checkliste für Ihre API

  • Ressourcen und Endpunkte folgen einem einheitlichen Schema, HTTP-Methoden werden korrekt verwendet.
  • Eine vollständige OpenAPI-Spezifikation mit Beispielen liegt im Repository und wird in der Pipeline geprüft.
  • Statuscodes und Fehlerformat (RFC 9457) sind einheitlich definiert.
  • Paginierung, Filter, Sortierung, Zeit- und Betragsformate sind geregelt.
  • Versionierungsstrategie, Breaking-Change-Regeln und Migrationsfenster sind dokumentiert.
  • Contract-Tests und eine Breaking-Change-Prüfung laufen automatisiert in der Pipeline.
  • Authentifizierung, Autorisierung auf Objektebene und Rate Limiting sind umgesetzt.
  • Zugriffe werden protokolliert, ohne sensible Daten zu speichern; die Nutzung pro Version ist auswertbar.

So unterstützt Nano Concepts

Wenn Sie eine neue API planen oder eine bestehende verbessern möchten, unterstützen wir Sie mit unserer API- und Backend-Entwicklung – vom Entwurf der OpenAPI-Beschreibung über die Umsetzung bis zur Anbindung bestehender Systeme. Im kostenlosen Erstgespräch klären wir, welche Schnittstellen Sie brauchen, wer sie nutzt und wie sich Änderungen künftig ohne Bruch ausrollen lassen.

Häufige Fragen

OpenAPI ist ein Standard, mit dem sich REST-APIs maschinenlesbar beschreiben lassen, früher als Swagger-Spezifikation bekannt. Die Beschreibung enthält Endpunkte, Parameter, Datenschemata, Beispiele und mögliche Antworten. Daraus lassen sich Dokumentation, Mock-Server, Clients und automatische Tests erzeugen.

Gängig ist die Hauptversion im Pfad, etwa /v1/, alternativ im Header. Wichtiger als die Methode ist der Prozess: Additive Änderungen brauchen keine neue Version, Breaking Changes nur mit Ankündigung, Changelog, Sunset-Datum und ausreichendem Parallelbetrieb. Messen Sie, welche Clients noch die alte Version nutzen.

Contract-Tests prüfen automatisiert, ob eine API die Erwartungen ihrer Konsumenten erfüllt, etwa mit Pact oder gegen die OpenAPI-Beschreibung. Sie laufen in der Pipeline bei jeder Änderung. So fallen unbeabsichtigte Brüche auf, bevor sie Partner oder andere Systeme beeinträchtigen.

Nutzen Sie die Statuscodes der HTTP-Spezifikation: 400 oder 422 für ungültige Eingaben, 401 und 403 für fehlende Anmeldung oder Berechtigung, 404, 409 für Konflikte und 429 bei zu vielen Anfragen. Für den Fehlertext empfiehlt sich das Format Problem Details nach RFC 9457.

REST eignet sich für Partner- und öffentliche Schnittstellen sowie klassische Datenabfragen, da Werkzeuge, Caching und Dokumentation weit verbreitet sind. GraphQL lohnt sich, wenn Clients sehr unterschiedliche Datenausschnitte flexibel abfragen. gRPC wird häufig für schnelle interne Kommunikation zwischen Diensten genutzt.

Passende Leistungen

Begriffe aus diesem Beitrag kurz erklärt

Sebastian MandlmeirRedaktion Nano ConceptsFachbeiträge aus der Praxis – verantwortet von Sebastian Mandlmeir, Geschäftsführer

Weitere Beiträge

In 60 Sekunden zum passenden Angebot

Bedarfsanalyse: REST-API mit OpenAPI

Beantworten Sie ein paar kurze Fragen – wir melden uns in der Regel innerhalb von 24 Stunden mit einer ersten Einschätzung.

Projekt anfragen