OpenAPI ist ein Standard zur Be­schrei­bung von Pro­gram­mier­schnitt­stel­len – Ap­pli­ca­ti­on Pro­gramming In­ter­faces (API). Die OpenAPI-Spe­zi­fi­ka­ti­on definiert ein offenes und her­stel­ler­neu­tra­les Be­schrei­bungs­for­mat für API-Dienste. Ins­be­son­de­re lassen sich mithilfe von OpenAPI REST-konforme APIs be­schrei­ben, ent­wi­ckeln, testen und do­ku­men­tie­ren.

Die heutige OpenAPI-Spe­zi­fi­ka­ti­on ging aus dem Vor­gän­ger­pro­jekt Swagger hervor. Die Ent­wick­lungs­fir­ma SmartBear stellte die exis­tie­ren­de Swagger-Spe­zi­fi­ka­ti­on unter eine offene Lizenz und übergab die Pflege und Wei­ter­ent­wick­lung an die OpenAPI-In­itia­ti­ve. Mit­glie­der der OpenAPI-In­itia­ti­ve sind neben SmartBear Bran­chen­grö­ßen wie Google, IBM und Microsoft; gefördert wird das Projekt auch von der Linux Foun­da­ti­on.

IONOS Ent­wick­ler API
Verwalten Sie Ihre IONOS Hosting-Produkte über unsere leis­tungs­star­ken APIs
  • DNS-Ma­nage­ment
  • SSL-Ver­wal­tung
  • API-Do­ku­men­ta­ti­on

OpenAPI im Überblick

Ein Punkt, der für Ver­wir­rung sorgen kann, ist die Un­ter­schei­dung zwischen OpenAPI und Swagger. Bei OpenAPI handelt es sich um eine Spe­zi­fi­ka­ti­on, d. h. eine abstrakte Be­schrei­bung, die nicht an eine spe­zi­fi­sche tech­ni­sche Im­ple­men­ta­ti­on gebunden ist. Bis zur Version 2.0 hieß diese Spe­zi­fi­ka­ti­on noch Swagger und wurde dann in OpenAPI-Spe­zi­fi­ka­ti­on umbenannt. Jedoch exis­tie­ren die von der ur­sprüng­li­chen Ent­wick­lungs­fir­ma SmartBear be­reit­ge­stell­ten Tools unter dem Namen Swagger weiter.

Mit OpenAPI lässt sich eine API auf ein­heit­li­che Weise be­schrei­ben. Man spricht dabei von der „API-De­fi­ni­ti­on“. Diese wird in einem ma­schi­nen­les­ba­ren Format erzeugt. Ins­be­son­de­re kommen dabei die beiden Sprachen YAML und JSON zum Einsatz.

Hinweis

Neben der API-De­fi­ni­ti­on hört man manchmal auch den Ausdruck „API-Spe­zi­fi­ka­ti­on“. Dabei handelt es sich um eine rein für den mensch­li­chen Be­trach­ter erstellte, abstrakte Be­schrei­bung einer API.

Technisch un­ter­schei­den sich YAML und JSON nur ge­ring­fü­gig, so dass es möglich ist, eine be­stehen­de API-De­fi­ni­ti­on au­to­ma­ti­siert von einer Sprache in die andere zu kon­ver­tie­ren. Jedoch weist YAML eine klarere Struktur auf und ist für den Menschen einfacher zu lesen. Hier ein Beispiel desselben OpenAPI-Server-Objekts, dar­ge­stellt 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-Spe­zi­fi­ka­ti­on definiert eine Reihe von Ei­gen­schaf­ten, die sich für den Aufbau einer eigenen API nutzen lassen. Diese Ei­gen­schaf­ten sind als so­ge­nann­te Objekte (engl. „Objects“) zu­sam­men­ge­fasst. In der aktuellen Version 3.0.3 legt OpenAPI u. a. die Struktur für die folgenden Objekte fest:

  • Info Object: Version, Name etc. der API
  • Contact Object: Kon­takt­in­for­ma­ti­on des API-Anbieters
  • License Object: Lizenz, unter der die API ihre Daten be­reit­stellt
  • Server Object: Hostnamen, URL-Struktur und Ports der Server, über die die API an­ge­spro­chen wird
  • Com­pon­ents Object: ge­kap­sel­te Kom­po­nen­ten, die sich innerhalb einer API-De­fi­ni­ti­on mehrfach verwenden lassen
  • Paths Object: relative Pfade zu End­punk­ten der API, die mit dem Server Object zusammen genutzt werden
  • Path Item Object: für einen spe­zi­fi­schen Pfad zulässige Ope­ra­tio­nen wie GET, PUT, POST, DELETE
  • Operation Object: legt u. a. die Parameter und die zu er­war­ten­den Server-Responses für eine Operation fest

Was sind die Ein­satz­ge­bie­te von OpenAPI?

Generell wird OpenAPI ein­ge­setzt, um REST-APIs auf ein­heit­li­che Weise zu be­schrei­ben. Da diese Be­schrei­bung, also die API-De­fi­ni­ti­on, in einem ma­schi­nen­les­ba­ren Format vorliegt, lassen sich daraus au­to­ma­ti­siert ver­schie­de­ne virtuelle Artefakte erzeugen. Dazu gehören ins­be­son­de­re:

  • Erzeugung von API-Do­ku­men­ta­ti­on: Aus der ma­schi­nen­les­ba­ren API-De­fi­ni­ti­on wird au­to­ma­ti­siert eine HTML-basierte Do­ku­men­ta­ti­on erzeugt. Diese dient als Nach­schla­ge­werk für Ent­wick­ler, die auf die Dienste der API zugreifen. Ändert sich die API-De­fi­ni­ti­on, wird die Do­ku­men­ta­ti­on neu erzeugt, so dass beide im Einklang bleiben.
  • Erzeugung von An­bin­dun­gen in ver­schie­de­nen Pro­gram­mier­spra­chen: Mittels ge­eig­ne­ter Tools kann aus der API-De­fi­ni­ti­on eine passende kli­en­ten­sei­ti­ge Software-Bi­blio­thek in einer un­ter­stütz­ten Pro­gram­mier­spra­che erzeugt werden. Somit wird Pro­gram­mie­rern un­ter­schied­lichs­ter Couleur der Zugriff auf die API er­mög­licht. Die Software-Bi­blio­thek wird ganz normal ein­ge­bun­den; Zugriffe auf die API-Dienste erfolgen dann z. B. über Funk­ti­ons­auf­ru­fe innerhalb der gewohnten Pro­gram­mier­um­ge­bung.
  • Erzeugung von Test­fäl­len: Jede Kom­po­nen­te einer Software muss Tests un­ter­zo­gen werden, um die Funk­tio­na­li­tät si­cher­zu­stel­len. Ins­be­son­de­re muss eine Software-Kom­po­nen­te bei jeder Änderung des zu­grun­de­lie­gen­den Codes erneut getestet werden. Aus der API-De­fi­ni­ti­on lassen sich diese Testfälle au­to­ma­ti­siert erzeugen, so dass die Funk­tio­na­li­tät der Software-Kom­po­nen­ten durch­ge­hend überprüft werden kann.

Der Voll­stän­dig­keit halber sei hier angemerkt, dass sich nicht jede beliebige API mittels OpenAPI abbilden lässt. REST-APIs werden jedoch explizit un­ter­stützt.

Was sind die Vorteile von OpenAPI?

Generell liegt der Vorteil von OpenAPI darin, bei der Ent­wick­lung und fort­lau­fen­den Pflege einer API deren Im­ple­men­ta­ti­on, Do­ku­men­ta­ti­on und Tests in Einklang zu halten. Ferner erlaubt die Nutzung der OpenAPI-Spe­zi­fi­ka­ti­on eine bessere Ko­or­di­na­ti­on der API-Ent­wick­lung zwischen Backend und Frontend. Auf beiden Seiten können aus der API-De­fi­ni­ti­on Code-Kom­po­nen­ten erzeugt werden, so dass Backend- und Frontend-Teams ent­wi­ckeln und testen können, ohne auf die jeweils andere Seite warten zu müssen.

Neben diesen ge­ne­rel­len Vorteilen wird OpenAPI ins­be­son­de­re als stan­dar­di­sier­te Basis für die Ent­wick­lung von REST-APIs ein­ge­setzt. Dies ist attraktiv, da es nicht trivial ist, eine REST-konforme API von Hand zu ent­wi­ckeln. 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:

  • HTTP-APIs un­ab­hän­gig von einer spe­zi­fi­schen Pro­gram­mier­spra­che de­fi­nie­ren
  • Server-Code für eine in OpenAPI de­fi­nier­te API ge­ne­rie­ren
  • Kli­en­ten­sei­ti­ge Bi­blio­the­ken für eine OpenAPI-konforme API in mehr als 40 Pro­gram­mier­spra­chen ge­ne­rie­ren
  • Eine OpenAPI-De­fi­ni­ti­on mit ge­eig­ne­ten Tools ver­ar­bei­ten
  • In­ter­ak­ti­ve API-Do­ku­men­ta­ti­on erstellen
  • Menschen und Maschinen er­mög­li­chen, die Ka­pa­zi­tä­ten eines Services zu entdecken und zu verstehen, ohne dafür Einsicht in den Quelltext oder zu­sätz­li­che Do­ku­men­ta­ti­on nehmen zu müssen.
  • Auf API-Services mit minimalem Im­ple­men­ta­ti­ons­auf­wand zugreifen

Welche OpenAPI-Versionen gibt es und wie un­ter­schei­den sich diese?

Zum Zeitpunkt der Ar­ti­kel­er­stel­lung ist die OpenAPI-Version 3.0.3 aktuell. Hier ein kurzer Überblick der vor­her­ge­hen­den Versionen:

Version Name Status
1.0, August 2011 Swagger-Spe­zi­fi­ka­ti­on nicht mehr in Benutzung
2.0, September 2014 Swagger-Spe­zi­fi­ka­ti­on → OpenAPI-Spe­zi­fi­ka­ti­on weiterhin un­ter­stützt
3.0, Juli 2017 OpenAPI-Spe­zi­fi­ka­ti­on weiterhin un­ter­stützt
Bild: OpenAPI-Versionen: Strukturelle Unterschiede zwischen OpenAPI v2.0 und v3.0
Insgesamt wurde die Struktur der OpenAPI-Spe­zi­fi­ka­ti­on ver­schlankt.

Neuer Name des Root-Objekts

Mit dem Er­schei­nen der Version 3.0 wurde das OpenAPI-Objekt ein­ge­führt, das das vormals benutzte Swagger-Objekt ersetzt:

# <= 2.0
"swagger": "2.0"
# >= 3.0
"OpenAPI": "3.0.0"

Mehrere Hosts/Server

Ab OpenAPI-Version 3.0 kann eine API über mehr als nur einen Server an­ge­spro­chen werden. Ferner ist es möglich, Teile der Server-URL variabel zu de­fi­nie­ren. 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"
                }
            }
        }
    ]

Neue Kom­po­nen­ten- und Referenz-Objekte

Bei den in OpenAPI-Version 3.0 hin­zu­ge­kom­me­nen Kom­po­nen­ten- und Referenz-Objekten handelt es sich um eine der größeren Neue­run­gen. Das Kom­po­nen­ten-Objekt erlaubt die De­fi­ni­ti­on mehrerer, innerhalb der API-De­fi­ni­ti­on wie­der­ver­wend­ba­rer Objekte. Diese so­ge­nann­ten Kom­po­nen­ten werden innerhalb der API-De­fi­ni­ti­on mithilfe des spe­zi­el­len Kon­strukts $ref ein­ge­bun­den.

Mittels der Kom­po­nen­ten und Re­fe­ren­zen ist es möglich, eine API-De­fi­ni­ti­on aus mehreren, wie­der­be­nutz­ba­ren Teilen auf­zu­bau­en. Dies er­leich­tert die Les­bar­keit und ver­rin­gert die Größe des gesamten Dokuments. Nach­fol­gend ein Beispiel aus der of­fi­zi­el­len GitHub-API-De­fi­ni­ti­on:

  1. Schema eines GitHub-Code-Re­po­si­to­rys, als Kom­po­nen­ten-Objekt definiert
  2. Lizenz-De­fi­ni­ti­on, über eine extern de­fi­nier­te Kom­po­nen­te re­fe­ren­ziert
"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"
                        }
                    ]
                },

OpenAPI im Einsatz: Zwei Beispiele

Die OpenAPI-Spe­zi­fi­ka­ti­on und die damit ver­bun­de­nen Tools, ins­be­son­de­re von Swagger, werden auf breiter Basis zur Er­stel­lung diverser APIs verwendet. Wir stellen hier zwei Beispiele vor:

GitHub v3 REST API

Der beliebte Git-Service GitHub nutzt OpenAPI, um die seine „GitHub v3 REST API“ zu be­schrei­ben. Die API-De­fi­ni­ti­on liegt auf GitHub als Re­po­si­to­ry vor. Mit ihrer Hilfe kann ein Nutzer genau er­schlie­ßen, welche Services über die GitHub-API an­ge­spro­chen werden können und wie genau die dabei zum Zuge kommenden Aufrufe struk­tu­riert sein müssen. Ferner kann ein jeder die API nutzen, um mittels ge­eig­ne­ter Tools dafür passenden Code zu erzeugen.

Laut GitHub dient die API-De­fi­ni­ti­on dazu, die REST API zu be­schrei­ben, zu erzeugen, zu kon­su­mie­ren und zu vi­sua­li­sie­ren. Zum Zeitpunkt der Ar­ti­kel­er­stel­lung liegt die API-De­fi­ni­ti­on nicht voll­stän­dig vor. So fehlen noch einige Header-Felder, die in Zukunft hin­zu­ge­fügt werden. Ferner wird darauf hin­ge­wie­sen, dass manche der möglichen API-Ope­ra­tio­nen über ver­schie­de­ne Pfade aus­ge­führt werden können, wobei ggf. nur ein Pfad in der Spe­zi­fi­ka­ti­on auf­ge­führt ist.

Aus Gründen der Kom­pa­ti­bi­li­tät bietet GitHub die API-De­fi­ni­ti­on in ver­schie­de­nen Formaten an. Zum einen existiert eine als gebündelt („bundled“) be­zeich­ne­te Version. Diese enthält die mit OpenAPI 3.0 ein­ge­führ­ten Kom­po­nen­ten und darauf ver­wei­sen­de Re­fe­ren­zen. Als Ge­gen­stück dazu wird eine als de­re­fe­ren­ziert („de­re­fe­ren­ced“) be­zeich­ne­te Version angeboten, in der die Re­fe­ren­zen allesamt aufgelöst sind. Aufgrund der dabei auf­tre­ten­den Redundanz ist die de­re­fe­ren­zier­te API-De­fi­ni­ti­on um etwa den Faktor drei größer als die ge­bün­del­te. Viele Tools un­ter­stüt­zen noch keine Re­fe­ren­zen; für diese Fälle bietet sich die de­re­fe­ren­zier­te API-De­fi­ni­ti­on an.

Sie können sich die API-De­fi­ni­ti­on selbst anschauen. Wir weisen darauf hin, dass die komplette Datei mehrere Megabyte groß ist. Für eine Textdatei handelt es sich dabei um eine un­glaub­lich große Menge an In­for­ma­tio­nen. Auf GitHub kann eine derartig große Datei nicht direkt dar­ge­stellt werden. Sie können aber den folgenden Link nutzen, um sich die GitHub REST API im Browser an­zu­schau­en. Hierbei handelt es sich um die deutlich kom­pak­te­re und besser lesbare YAML-Version: GitHub REST API (YAML).

Petstore-Beispiel-API von Swag­ger­Hub

Als zweites verweisen wir auf eine Beispiel-API, die bei Swag­ger­Hub erzeugt werden kann. Swag­ger­Hub ist eine On­line­platt­form für Design und Ent­wick­lung von REST-APIs mit OpenAPI. Sie können sich dort ein kos­ten­lo­ses Nut­zer­kon­to ein­rich­ten; zum Anmelden genügt aber auch ein bereits be­stehen­des Nut­zer­kon­to bei GitHub.

Sobald Sie in Swag­ger­Hub ein­ge­loggt sind, können Sie eine neue API erstellen. Dabei gibt es die Mög­lich­keit, auf einem be­stehen­den Template auf­zu­set­zen. Bei­spiels­wei­se existiert ein API-Template für einen vir­tu­el­len „Petstore“, also einen Tierladen. Die mit dem Template erzeugte Petstore-API umfasst ein breites Spektrum an OpenAPI-Objekten. Dazu gehören u. a.:

  • Kon­takt­in­for­ma­ti­on, Nut­zungs­be­din­gun­gen, Lizenz etc.
  • Die API-Endpoints und die Ope­ra­tio­nen eines jeden Endpoints
  • Die erlaubten Eingabe- und Ausgabe-Parameter der Ope­ra­tio­nen
  • Si­cher­heits­vor­ga­ben

Schaut man sich die Petstore-API an, kann man eine Menge darüber lernen, wie OpenAPI funk­tio­niert. Ferner dient die Petstore-De­fi­ni­ti­on als ein gutes Beispiel für den Aufbau einer REST-konformen API. Ab­schlie­ßend sei ein Code-Beispiel aus der Petstore-API gegeben. Wir ana­ly­sie­ren den nach­fol­gen­den Code-Abschnitt:

  1. Der Code definiert den API-Endpoint '/pet'.
  2. Mit einem HTTP-POST Request wird ein neues Tier dem Tierladen hin­zu­ge­fügt.
  3. Nutzen Sie statt­des­sen das HTTP-Verb PUT am selben Endpoint, können Sie ein bereits vor­han­de­nes Tier verändern.
  4. Für die Ope­ra­tio­nen sind ver­schie­de­ne Server-Antworten definiert. Die dafür fest­ge­leg­ten HTTP-Sta­tus­codes umfassen in diesem Beispiel den bekannten Sta­tus­code 404 „Not Found“. Dieser wird im Fall der Petstore-API als „Pet not found“ sti­li­siert.
Hinweis

Bei den mit '$ref' be­gin­nen­den und mit „OpenAPI 3.0+ Component“ kom­men­tier­ten Code­zei­len handelt es sich um Re­fe­ren­zen zu in­di­vi­du­ell de­fi­nier­ten OpenAPI-Kom­po­nen­ten.

# 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'
Fazit

OpenAPI hat sich als offenes und her­stel­ler­neu­tra­les Be­schrei­bungs­for­mat für API-Dienste etabliert. Es ist zu erwarten, dass OpenAPI innerhalb der ab­seh­ba­ren Zukunft als Standard für den Aufbau von REST-APIs breite Ver­wen­dung finden wird.

Zum Hauptmenü