REST API: Meta-Informationen und Versionierung

Dieser Artikel beschreibt den Tab Meta-Informationen einer REST-API-Definition und die unterstützten Versionierungsansätze. Eine Übersicht über die Konfiguration finden Sie unter REST API.

Tab „Meta-Informationen"

Im Tab Meta-Informationen hinterlegen Sie informative Angaben zur REST API. Diese Angaben erscheinen je nach Aufrufkontext in der OpenAPI-Dokumentation.

Die Plattform speichert die Informationen im Feld meta der Klasse REST API (RestApi). Das Feld enthält ein RestApiMetadata-Datenobjekt mit folgender Struktur:

Eigenschaft	Datentyp	Datenfeld (Pfad)	Hinweise
Info	`RestApiMetadata`	`(meta)`
Titel	`String`	`title`
Version	`String`	`version`	Typisches Format: `<major>.<minor>.<patch>`. Rein informativ. Details siehe Abschnitt „API-Versionierung".
Zusammenfassung	`String`	`summary`
Beschreibung	`String`	`description`
Nutzungsbedingungen	`String`	`termsOfService`
Kontakt	`RestApiMetadata$Contact`	`contact`	Datenfeldpfad bezieht sich auf das `RestApiMetadata`-Objekt im Feld `meta`.
Kontakt > Name	`String`	`contact.name`
Kontakt > URL	`String`	`contact.url`
Kontakt > E-Mail	`String`	`contact.email`
Lizenz	`RestApiMetadata$License`	`license`	Datenfeldpfad bezieht sich auf das `RestApiMetadata`-Objekt im Feld `meta`.
Lizenz > Name	`String`	`license.name`
Lizenz > URL	`String`	`license.url`
Lizenz > Kennung	`String`	`license.identifier`

API-Versionierung

Sobald Sie serverseitige Funktionen per API veröffentlichen, stellt sich die Frage nach Versionierung. Die REST-API-Konfiguration unterstützt mehrere Ansätze. Mehrere Versionen eines Endpunkts lassen sich parallel veröffentlichen und betreiben. Die Außerbetriebnahme (Deprecation) einzelner Endpunkte (Sunset, Statuscode 410 Gone) beschreibt der Artikel REST API: Erweiterte Endpunkt-Einstellungen.

Query-Parameter und Request-Header sind empfohlene Konventionen und keine eigene Plattformfunktion: Die Plattform stellt nur die generischen Maps queryParameters und requestHeaders bereit; die Auswertung der Version übernimmt Ihr Aktionsblock.

Versionsangabe in der Basis-URI

Die Eigenschaft Basis-URI (baseUri) kann eine statische Versionsnummer enthalten. Üblich ist, der Versionsnummer den Buchstaben v voranzustellen. Beispiel: v2/lookup innerhalb einer Endpunkt-URL wie ./api/v2/lookup/item/4711.

Versionsangabe in der Endpunkt-URI

Auch innerhalb der Eigenschaft URI (uri) eines Endpunkts platzieren Sie eine Versionsangabe. Beispiel: v2/getItem/{id} innerhalb einer Endpunkt-URL wie ./api/lookup/v2/getItem/4711.

Version als URI-Parameter

Innerhalb der URI bilden Sie die Versionsnummer auch auf eine Variable ab. Beispiel: v{version}/getItem{id} für die Endpunkt-URL ./api/lookup/v2/getItem/4711. Der Aktionsblock unterscheidet dann fallweise über die Variable version, zum Beispiel mit Wenn Dann Sonst oder Bedingter Wert.

Version als Query-Parameter

Den Versionsindex platzieren Sie alternativ als Query-Parameter. Im Aktionsblock greifen Sie über die Map queryParameters darauf zu. Beispiel: ./api/lookup/getItem/4711?v=2.

Version als Request-Header

Auch über die Map requestHeaders bringen Sie eine Versionskennung als Header-Parameter in den Aktionsblock. Die Versionsangabe erscheint dann nicht in der URL, ist aber im Aktionsblock erreichbar.

HINWEIS Die Versionsangabe im Tab Meta-Informationen nutzt die Plattform rein informativ für die OpenAPI-Dokumentation. Sie beeinflusst das Routing nicht; dieses steuert ausschließlich Basis-URI und Endpunkt-URI. Die dort angezeigte Version kann irreführend sein, wenn sich mehrere aktive REST-API-Definitionen auf dieselbe Basis-URI beziehen.

Documentation Index