OpenAPI ist ein Standard zur Beschreibung von Programmierschnittstellen – Application Programming Interfaces (API). Die OpenAPI-Spezifikation definiert ein offenes und herstellerneutrales Beschreibungsformat für API-Dienste. Insbesondere lassen sich mithilfe von OpenAPI REST-konforme APIs beschreiben, entwickeln, testen und dokumentieren.
Die heutige OpenAPI-Spezifikation ging aus dem Vorgängerprojekt Swagger hervor. Die Entwicklungsfirma SmartBear stellte die existierende Swagger-Spezifikation unter eine offene Lizenz und übergab die Pflege und Weiterentwicklung an die OpenAPI-Initiative. Mitglieder der OpenAPI-Initiative sind neben SmartBear Branchengrößen wie Google, IBM und Microsoft; gefördert wird das Projekt auch von der Linux Foundation.
Ein Punkt, der für Verwirrung sorgen kann, ist die Unterscheidung zwischen OpenAPI und Swagger. Bei OpenAPI handelt es sich um eine Spezifikation, d. h. eine abstrakte Beschreibung, die nicht an eine spezifische technische Implementation gebunden ist. Bis zur Version 2.0 hieß diese Spezifikation noch Swagger und wurde dann in OpenAPI-Spezifikation umbenannt. Jedoch existieren die von der ursprünglichen Entwicklungsfirma SmartBear bereitgestellten Tools unter dem Namen Swagger weiter.
Mit OpenAPI lässt sich eine API auf einheitliche Weise beschreiben. Man spricht dabei von der „API-Definition“. Diese wird in einem maschinenlesbaren Format erzeugt. Insbesondere kommen dabei die beiden Sprachen YAML und JSON zum Einsatz.
Neben der API-Definition hört man manchmal auch den Ausdruck „API-Spezifikation“. Dabei handelt es sich um eine rein für den menschlichen Betrachter erstellte, abstrakte Beschreibung einer API.
Technisch unterscheiden sich YAML und JSON nur geringfügig, so dass es möglich ist, eine bestehende API-Definition automatisiert von einer Sprache in die andere zu konvertieren. Jedoch weist YAML eine klarere Struktur auf und ist für den Menschen einfacher zu lesen. Hier ein Beispiel desselben OpenAPI-Server-Objekts, dargestellt in YAML und JSON:
# YAML
servers:
- url: https://development.example.com/v1
description: Development server
- url: https://staging.example.com/v1
description: Staging server
- url: https://api.example.com/v1
description: Production server// JSON
{
"servers": [
{
"url": "https://development.example.com/v1",
"description": "Development server"
},
{
"url": "https://staging.example.com/v1",
"description": "Staging server"
},
{
"url": "https://api.example.com/v1",
"description": "Production server"
}
]
}Die OpenAPI-Spezifikation definiert eine Reihe von Eigenschaften, die sich für den Aufbau einer eigenen API nutzen lassen. Diese Eigenschaften sind als sogenannte Objekte (engl. „Objects“) zusammengefasst. In der aktuellen Version 3.0.3 legt OpenAPI u. a. die Struktur für die folgenden Objekte fest:
Generell wird OpenAPI eingesetzt, um REST-APIs auf einheitliche Weise zu beschreiben. Da diese Beschreibung, also die API-Definition, in einem maschinenlesbaren Format vorliegt, lassen sich daraus automatisiert verschiedene virtuelle Artefakte erzeugen. Dazu gehören insbesondere:
Der Vollständigkeit halber sei hier angemerkt, dass sich nicht jede beliebige API mittels OpenAPI abbilden lässt. REST-APIs werden jedoch explizit unterstützt.
Generell liegt der Vorteil von OpenAPI darin, bei der Entwicklung und fortlaufenden Pflege einer API deren Implementation, Dokumentation und Tests in Einklang zu halten. Ferner erlaubt die Nutzung der OpenAPI-Spezifikation eine bessere Koordination der API-Entwicklung zwischen Backend und Frontend. Auf beiden Seiten können aus der API-Definition Code-Komponenten erzeugt werden, so dass Backend- und Frontend-Teams entwickeln und testen können, ohne auf die jeweils andere Seite warten zu müssen.
Neben diesen generellen Vorteilen wird OpenAPI insbesondere als standardisierte Basis für die Entwicklung von REST-APIs eingesetzt. Dies ist attraktiv, da es nicht trivial ist, eine REST-konforme API von Hand zu entwickeln. Jedoch haben REST-APIs einige Vorteile. So läuft REST über HTTP/S und die Ports dafür sind in jeder Firewall offen.
Ferner bietet die Nutzung von OpenAPI die folgenden Vorteile:
Zum Zeitpunkt der Artikelerstellung ist die OpenAPI-Version 3.0.3 aktuell. Hier ein kurzer Überblick der vorhergehenden Versionen:
| Version | Name | Status |
|---|---|---|
| 1.0, August 2011 | Swagger-Spezifikation | nicht mehr in Benutzung |
| 2.0, September 2014 | Swagger-Spezifikation → OpenAPI-Spezifikation | weiterhin unterstützt |
| 3.0, Juli 2017 | OpenAPI-Spezifikation | weiterhin unterstützt |
Mit dem Erscheinen der Version 3.0 wurde das OpenAPI-Objekt eingeführt, das das vormals benutzte Swagger-Objekt ersetzt:
# <= 2.0
"swagger": "2.0"
# >= 3.0
"OpenAPI": "3.0.0"Ab OpenAPI-Version 3.0 kann eine API über mehr als nur einen Server angesprochen werden. Ferner ist es möglich, Teile der Server-URL variabel zu definieren. Hier ein Beispiel:
"servers": [
{
"url": "https://{username}.example.com:{port}/{basePath}",
"description": "The production API server",
"variables": {
"username": {
"default": "demo",
"description": "this value is assigned by the service provider, in this example `example.com`"
},
"port": {
"enum": [
"8443",
"443"
],
"default": "8443"
},
"basePath": {
"default": "v2"
}
}
}
]Bei den in OpenAPI-Version 3.0 hinzugekommenen Komponenten- und Referenz-Objekten handelt es sich um eine der größeren Neuerungen. Das Komponenten-Objekt erlaubt die Definition mehrerer, innerhalb der API-Definition wiederverwendbarer Objekte. Diese sogenannten Komponenten werden innerhalb der API-Definition mithilfe des speziellen Konstrukts $ref eingebunden.
Mittels der Komponenten und Referenzen ist es möglich, eine API-Definition aus mehreren, wiederbenutzbaren Teilen aufzubauen. Dies erleichtert die Lesbarkeit und verringert die Größe des gesamten Dokuments. Nachfolgend ein Beispiel aus der offiziellen GitHub-API-Definition:
"components": {
"schemas": {
// Repository-Schema
"repository": {
"title": "Repository",
"description": "A git repository",
"type": "object",
"properties": {
"id": {
"description": "Unique identifier of the repository",
"example": 42,
"type": "integer"
},
"node_id": {
"type": "string",
"example": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5"
},
"name": {
"description": "The name of the repository.",
"type": "string",
"example": "Team Environment"
},
"full_name": {
"type": "string",
"example": "octocat/Hello-World"
},
// Lizenz-Definition
"license": {
"nullable": true,
"allOf": [
{
// Referenz auf extern definierte Komponente
"$ref": "#/components/schemas/license-simple"
}
]
},Die OpenAPI-Spezifikation und die damit verbundenen Tools, insbesondere von Swagger, werden auf breiter Basis zur Erstellung diverser APIs verwendet. Wir stellen hier zwei Beispiele vor:
Der beliebte Git-Service GitHub nutzt OpenAPI, um die seine „GitHub v3 REST API“ zu beschreiben. Die API-Definition liegt auf GitHub als Repository vor. Mit ihrer Hilfe kann ein Nutzer genau erschließen, welche Services über die GitHub-API angesprochen werden können und wie genau die dabei zum Zuge kommenden Aufrufe strukturiert sein müssen. Ferner kann ein jeder die API nutzen, um mittels geeigneter Tools dafür passenden Code zu erzeugen.
Laut GitHub dient die API-Definition dazu, die REST API zu beschreiben, zu erzeugen, zu konsumieren und zu visualisieren. Zum Zeitpunkt der Artikelerstellung liegt die API-Definition nicht vollständig vor. So fehlen noch einige Header-Felder, die in Zukunft hinzugefügt werden. Ferner wird darauf hingewiesen, dass manche der möglichen API-Operationen über verschiedene Pfade ausgeführt werden können, wobei ggf. nur ein Pfad in der Spezifikation aufgeführt ist.
Aus Gründen der Kompatibilität bietet GitHub die API-Definition in verschiedenen Formaten an. Zum einen existiert eine als gebündelt („bundled“) bezeichnete Version. Diese enthält die mit OpenAPI 3.0 eingeführten Komponenten und darauf verweisende Referenzen. Als Gegenstück dazu wird eine als dereferenziert („dereferenced“) bezeichnete Version angeboten, in der die Referenzen allesamt aufgelöst sind. Aufgrund der dabei auftretenden Redundanz ist die dereferenzierte API-Definition um etwa den Faktor drei größer als die gebündelte. Viele Tools unterstützen noch keine Referenzen; für diese Fälle bietet sich die dereferenzierte API-Definition an.
Sie können sich die API-Definition selbst anschauen. Wir weisen darauf hin, dass die komplette Datei mehrere Megabyte groß ist. Für eine Textdatei handelt es sich dabei um eine unglaublich große Menge an Informationen. Auf GitHub kann eine derartig große Datei nicht direkt dargestellt werden. Sie können aber den folgenden Link nutzen, um sich die GitHub REST API im Browser anzuschauen. Hierbei handelt es sich um die deutlich kompaktere und besser lesbare YAML-Version: GitHub REST API (YAML).
Als zweites verweisen wir auf eine Beispiel-API, die bei SwaggerHub erzeugt werden kann. SwaggerHub ist eine Onlineplattform für Design und Entwicklung von REST-APIs mit OpenAPI. Sie können sich dort ein kostenloses Nutzerkonto einrichten; zum Anmelden genügt aber auch ein bereits bestehendes Nutzerkonto bei GitHub.
Sobald Sie in SwaggerHub eingeloggt sind, können Sie eine neue API erstellen. Dabei gibt es die Möglichkeit, auf einem bestehenden Template aufzusetzen. Beispielsweise existiert ein API-Template für einen virtuellen „Petstore“, also einen Tierladen. Die mit dem Template erzeugte Petstore-API umfasst ein breites Spektrum an OpenAPI-Objekten. Dazu gehören u. a.:
Schaut man sich die Petstore-API an, kann man eine Menge darüber lernen, wie OpenAPI funktioniert. Ferner dient die Petstore-Definition als ein gutes Beispiel für den Aufbau einer REST-konformen API. Abschließend sei ein Code-Beispiel aus der Petstore-API gegeben. Wir analysieren den nachfolgenden Code-Abschnitt:
Bei den mit '$ref' beginnenden und mit „OpenAPI 3.0+ Component“ kommentierten Codezeilen handelt es sich um Referenzen zu individuell definierten OpenAPI-Komponenten.
# Petstore API Template #
# API Endpoint '/pet'
/pet:
# HTTP-POST Request
post:
tags:
- pet
summary: Add a new pet to the store
operationId: addPet
# HTTP-Status codes
responses:
'405':
description: Invalid input
security:
# Permissions
- petstore_auth:
- 'write:pets'
- 'read:pets'
requestBody:
# OpenAPI 3.0+ Component
$ref: '#/components/requestBodies/Pet'
# HTTP-PUT Request
put:
tags:
- pet
summary: Update an existing pet
operationId: updatePet
# HTTP-Status codes
responses:
'400':
description: Invalid ID supplied
'404':
description: Pet not found
'405':
description: Validation exception
security:
# Permissions
- petstore_auth:
- 'write:pets'
- 'read:pets'
requestBody:
# OpenAPI 3.0+ Component
$ref: '#/components/requestBodies/Pet'OpenAPI hat sich als offenes und herstellerneutrales Beschreibungsformat für API-Dienste etabliert. Es ist zu erwarten, dass OpenAPI innerhalb der absehbaren Zukunft als Standard für den Aufbau von REST-APIs breite Verwendung finden wird.
Continuous Integration kann die Arbeit bei der Software-Entwicklung verbessern: weniger Fehler und effizientere, kontinuierliche Integration. Doch dafür Bedarf es eines unkomplizierten und dennoch umfangreichen Werkzeugs. Deshalb stellen wir Ihnen in dieser Einführung Jenkins vor. Diese Software erleichtert Ihnen die Arbeit mit automatischen Builds und individuellen Pipelines. Damit Sie am Anfang...
Wer Software entwickelt, hat viel zu beachten: Eine gute Usability ist ebenso wichtig wie die Funktionalität der Anwendung; gleichzeitig ist eine optimale Performance – im Gegensatz zu Programmfehlern – unverzichtbar. Schließlich soll das Produkt auch auf den anvisierten Zielplattformen bzw. -geräten laufen. Inwiefern helfen Software Development Kits (SDKs) bei der Realisierung dieser Punkte?
In der Softwareentwicklung ist der Begriff Cloud Native seit einiger Zeit in aller Munde. Aber was ist Cloud Native eigentlich genau und wie wird das Konzept erfolgreich angewandt? Die agile Entwicklungsmethode zielt darauf ab, Anwendungen so zu entwickeln, dass sie sich nahtlos in eine Cloud-Infrastruktur integrieren lassen. Erfahren Sie hier mehr zu den Merkmalen und Vorteilen der...
Schnell, sicher und State-of-the-Art – nutzen Sie unsere starke Plattform für Ihre Kunden
