OpenAPI
OpenAPI beschreibt HTTP-Schnittstellen maschinenlesbar: mit Pfaden, Parametern und Antworten. Beschreibung und laufende Umsetzung müssen übereinstimmen.
Einen HTTP-API-Vertrag nachvollziehbar festhalten
OpenAPI ist ein Standard zur Beschreibung von HTTP-APIs. Eine OpenAPI-Beschreibung hält unter anderem angebotene Pfade, Operationen, Parameter und Antwortstrukturen fest. Sie kann als JSON oder YAML dargestellt werden. Die Beschreibungssprache hängt nicht von der Programmiersprache ab, in der der Dienst gebaut ist.
Ein fiktives Softwareunternehmen plant für sein Projektportal GET /projects/{projectId}. In der Beschreibung soll projectId als Pfadparameter festgelegt werden; für die erfolgreiche Antwort 200 ist unter anderem das Textfeld name vorgesehen. Auch bekannte Fehlerantworten gehören zum Vertrag. Pfad und Felder sind eigene Entwurfsbeispiele, kein vollständiges OpenAPI-Dokument und kein vorhandener Dienst.
Das Frontend-Team kann daran erkennen, welche Angaben es senden und welche Antworten es verarbeiten soll. Die Datei allein zeigt jedoch nicht, ob die laufende Implementierung diesen Vertrag einhält. Vor der Übergabe wären Beschreibung und tatsächliche Antworten einschließlich der Fehlerfälle abzugleichen. Auch die Bedeutung von name muss vereinbart sein: Ein korrekt typisierter Text erklärt noch nicht, welchen Namen das Feld enthält.
Quellen
Verwandte Begriffe
- APIEine API legt fest, wie Software Funktionen oder Daten anderer Software nutzen kann.
- RESTREST beschreibt Regeln für verteilte Schnittstellen. Ressourcen, zustandslose Anfragen und Verknüpfungen gehören zum Architekturansatz.
- Server-Sent EventsServer-Sent Events übertragen über eine HTTP-Verbindung Textmeldungen vom Server zum Client, etwa zum Fortschritt eines Hintergrundauftrags.
- Entity TagEin ETag kennzeichnet eine bestimmte Darstellungsversion einer HTTP-Ressource und ermöglicht bedingte Abrufe oder Änderungen.
- Cross-Origin Resource SharingCORS steuert im Browser die Freigabe von Antworten über Origin-Grenzen. Es ersetzt weder die Anmeldung noch die Berechtigungsprüfung einer API.
- Electronic Data InterchangeEDI überträgt strukturierte Geschäftsdokumente zwischen Systemen. Format, Partnerprofil, Datenzuordnung und Rückmeldungen müssen zusammenpassen.
Ihr Vorhaben mit ASES
Beschreiben Sie uns Ihr Vorhaben. Wir melden uns mit einer ersten Einschätzung.