OpenAPI-Spezifikation (OAS)

Die inzwischen hohe Vernetzung und Digitalisierung in der Wirtschaft, Industrie, Verwaltung und im privaten Umfeld erfordert auch immer hochwertigere Dienste und Anforderungen an die Softwarestrukturen. Datenbasierte Ökosysteme und Plattformen verwenden inzwischen komplexe und leistungsstarke API-Schnittstellen, um die Geschäftsanforderungen umsetzen zu können. Offenen Schnittstellen für die vielseitige Anwendbarkeit der Daten und Informationen stellen hier eine zentrale Schlüsselposition dar. Je komplexer eine Schnittstelle ausgelegt werden muss, umso wichtiger ist hier eine möglichst offene und definierte Struktur. Diese wird dann mit einer entsprechenden Beschreibungssprache dokumentiert und belegt.

Mit Open-API steht den Entwicklern eine moderne und leistungsfähige API-Beschreibungssprache für Ihre Projekte zur Verfügung. Basierend auf den bereits sehr erfolgreich im Markt etablierten Open-Source Tools von Swagger hat sich bereits 2015 unter der Federführung der Linux-Fundation aus der Open-API Initiative das neue Projekt Open-API gegründet. Zu dieser Initiative gehören derzeit 26 aktive Mitglieder, in der nicht wenige Big-Player mit von der Partie sind. Hier finden sich dann renommierte Unternehmen wie Microsoft, Google, SAP, Paypal, Adobe, Smartbear oder MuleSoft wieder. Dies sorgt für eine umfassende Kompatibilität und Struktur bei den bereitgestellten und veröffentlichten Diensten.

Seit nun mehr 2017 steht die Version 3 zur Projektierung und Umsetzung von leistungsstarken APIs zur Verfügung. Einer der größten Vorteile von Open-API ist die umfassende Sprachenunterstützung für Java, JScript, .Net, Ruby, Scala oder auch Gitlab. Diese basieren allesamt auf den Formaten von JSON oder auch YAML 1.2 und stellen damit eine sehr hohe Kompatibilität zur Verfügung. Weitere Neuerungen finden sich in der endlich angepassten und erweiterten Unterstützung des JSON-Schemas. Zudem fanden Neuerungen und Neustrukturierungen in den Bereichen Sicherheit und Hosts Einzug. Besonders komfortabel wurde die Wiederverwendung von Komponenten gelöst. In einem eigenen Bereich können nun HTTP-Header, Requests, Responses, Parameter, Callbacks, Links, Objektschemata und Beispiele abgelegt werden.

Die Kernelemente von Open API

Bereits während der Planung eines API sollen die Anforderungen klar definiert werden. Hier gilt es im besonderen Maße auf die Kernelemente der Funktionalität und späteren Dokumentation einzugehen. Jeder Anwender einer API muss auf die Informationen der verwendeten Parameter, Endpunkte, Rückgabewerte und Sicherheitsfaktoren zugreifen können. Nur so ist eine optimale und effiziente Nutzung der Schnittstelle möglich. Es existieren verschiedene Gruppen von Kernangaben in der Open API, auf die wir im Folgenden detaillierter eingehen werden.

Dokumentation

Um die einzelnen Bestandteile der API klar abbilden zu können, werden in der Regel auch externe Dokumente zur Erläuterung der API-Funktionen, Parameter, Endpunkte oder Angaben zur Webseite wie Nutzungsbedingungen etc. zur Verfügung gestellt. In dem Bereich Docs können entsprechende Verweise auf diese Dokumente und Schemata eingefügt werden. Das folgende Beispiel zeigt das zu verwendende Format:

externalDocs:
  description: Learn more about user operations provided by this API.
  url: http://api.api-portal.io/docs/user-operations/

Hinter dem Parameter description: wird eine kurze Beschreibung der Dokumentinhalte eingefügt. Mit dem Parameter url: wird dann auch der Link auf die Dokument-Ressource zur Verfügung gestellt.

Details

Innerhalb der Sektion Details werden sämtliche Basisinformationen zur API zur Verfügung gestellt. Diese Informationen sind auch API-weit gültig. Dieser Bereich verfügt über wichtige Parameter, die grundsätzlich eingetragen werden sollten. Der folgende Quelltextauszug beschreibt die einzelnen Werte im benötigten Format:

info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
- url: http://api.api-portal.io/v1
  description: Optional server description, e.g. Main (production) server
- url: http://staging.api-portal.io/v2
  description: Optional server description, e.g. Internal staging server for testing

Der erste Abschnitt info: beschreibt die Funktion der API mit kurzen Worten. Der Parameter title: nennt einen frei wählbaren Titel für die API, der zweite Parameter description: nennt die Kernfunktion dieser API und darf auch externe Links zu einer Referenzquelle beinhalten.

Der Abschnitt version: spricht für sich und bildet die aktuell verwendete API-Version ab. Diese Information ist bei unterschiedlichen Revisionen einer API besonders wertvoll.

Im Abschnitt servers: wird nun der aktive Host dieser API aufgeführt. Im Parameter url: wird jeder verwendete Basispfad einzeln und detailliert aufgeführt. Mit dem Parameter description: folgt eine jeweils kurze Beschreibung des Pfades.

Security

Mit dem Abschnitt Security werden alle in der API verwendeten und zugelassenen Authentifizierungsmethoden beschrieben. Zu jedem Eintrag existieren verschiedene Parameter, die auf die Verwendung des Schemas verweisen. Der folgende Quelltextauszug zeigt exemplarisch die korrekte Verwendung:

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    OpenID:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access
            admin: Grants access to admin operations

Neben Basic- und Bearer-Auth können auch weitere Schemas angegeben werden. Bei OAuth2 werden mehrere Angaben zu den URLs und den Gültigkeitsbereichen (scopes) vergeben. Hier kann dann gezielt die Zugriffsebene benannt werden. Sobald die Security-Regel im Root eingetragen wird, hat sie für die gesamte API entsprechende Gültigkeit. Hier ein mögliches Szenario, bei dem das Security-Schema OAuth2 nur Schreib- und Lesezugriffe erlaubt:

security:
  - ApiKeyAuth: []
  - OAuth2:
    - read
    - write

Weiterhin unterscheidet man auch die möglichen Authentifizierungsmethoden bezüglich der einzelnen Ressourcen-Operationen wie Lesen und Schreiben. Im folgenden Beispiel wird speziell für den Lesezugriff auf Rechnungsinformationen die Methode OAuth2 mit Adminrechten definiert:

paths:
  /billing_info:
    get:
      summary: Gets the account billing info
      security:
        - OAuth2: [admin] # Use OAuth with a different scope
      responses:
        '200':
          description: OK

Ressources

In der Regel verwendet ein API über unterschiedlichste Ressourcen wie Dateien, Formulare oder andere Informationen. Um an diese Daten zu kommen, sind im http-Protokoll auch verschiedene Anfrage- und Zugriffsmethoden definiert. Damit wird beispielsweise einem Browser signalisiert, wie er mit der Anfrage umzugehen hat. Grundsätzlich sind hier 4 Standard-Anfragemethoden vorgesehen, die auf Ressourcen angewendet werden können. Im Folgenden stellen wir diese nebst einer einfachen Beispiel-Parametrisierung vor:

GET - Mit dieser HTTP-Methode kann eine Ressource eingelesen werden. Zu beachten ist, dass eine GET-Methode keine Bestandsdaten am Server verändern darf. Um einen bestimmten Eintrag über den Identifier zu finden und auszulesen, setzen Sie die folgende Abfragemethode ein: GET /user/{userID}

POST – Die POST-Methode wird in der Regel dazu verwendet, eine neue Ressource zu erstellen, deren URI dem System noch nicht bekannt ist. Dies ist die Standard-Methode zum Anfügen einer neuen Ressource: POST /user 2

PUT – Mit dieser Methode wird das Bearbeiten bzw. Ändern einer bereits bestehenden und bekannten Ressource durchgeführt. Diese Methode wird vor allem für Updates von Daten angewendet: PUT /user 2

DELETE – Um eine bekannte und vorhandene Ressource zu löschen, wird die DELETE-Methode mit dem Identifier verwendet. Beachten Sie hierbei die Ressourcen-Rechte, ob der Methodenaufruf mit den Userrechten überhaupt durchgeführt werden kann: DELETE /user/{userID}

Für jede einzelne Ressource werden die entsprechenden Methodenparameter detailliert angegeben. Der folgende Quelltext zeigt exemplarisch die Suche nach einem Benutzerdatensatz an. Als Rückgabewerte werden der Statuscode 200 für die erfolgreiche Abfrage und die Codes 400 bzw. 404 für Fehlermeldungen definiert:

paths:
  /user/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the user to return.
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        '200':
          description: A user object.
          content:
            application/json:
              schema:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                  example: 4
                name:
                  type: string
                  example: Jessica Smith
        '400':
          description: The specified user ID is invalid (not a number).
        '404':
          description: A user with the specified ID was not found.
          default:
          description: Unexpected error

Types

In den Typendefinitionen der API werden alle verwendeten Geschäftsobjekte detailliert mit ID und den Eigenschaften nebst Wertebereichen beschrieben. Dabei werden auch beschreibende Kategorien verwendet, um die Objekt besser klassifizieren zu können. Im folgenden Beispiel erzeugen Sie ein wiederverwendbares Objekt im Component-Container mit allen relevanten Eigenschaften, Datentypen und Scopes:

components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

Errors

Zu jedem API-Request sollten auch ein oder mehrere Statusmeldungen definiert werden. Dies gilt insbesondere für auftretende Fehler. Je genauer Sie jeden API-Aufruf mit Error-Codes ausstatten, umso einfacher wird das Handling der Schnittstelle ausfallen. Unter dem Parameter responses definieren Sie alle Fehlercodes die zurückgegeben werden können. Dokumentieren Sie mit dem Parameter description: auch die Art der Fehlermeldung als Hinweis auf die Quelle.

Vor- und Nachteile von Open API

Mit der neuen Version 3 der Open API sind viele Fehler bereinigt worden und auch längst fällige Neuerungen dazugekommen. Die große Community und die breite Anwendung durch die Swagger-Tools werden eine schnelle Standardisierung beflügeln. Auch die Teilnahme vieler Big-Player und der nicht vorhandene Vendor-Lock sorgen für mächtig Vorschub. Viele namhafte Frameworks setzen inzwischen auch auf eine breite Open API Unterstützung. Vor allem die breite Neustrukturierung in der Userverwaltung und im Header-Bereich erleichtern den Umgang enorm. Ein weiterer klarer Vorteil sind die nun wiederverwendbaren Objekte über eine eigene Sektion.

Doch dort wo Licht, ist meist auch Schatten zu finden. Derzeit sind nur wenige Tools und Entwicklungsumgebungen speziell auf Open API ausgerichtet. Auch die Wiederverwendung von Code-Snippets ist noch nicht vorhanden und es bestehen gewisse Inkompatibilitäten zwischen den Versionen. Diese Unzulänglichkeiten werden aber sicherlich in absehbarer Zeit ausgeräumt.

Fazit

Die Auszeichnungssprache Open API hat sehr viele Vorteile und damit auch Gemeinsamkeiten mit RAML. Durch die relativ gute Auswahl an Code-Generatoren und den vielen Tools im Ökosystem werden viele Projektleiter jedoch Open API den Vorzug geben. Wer großen Wert auf umfangreiche Sprachenunterstützung legt, ist hier genau richtig. Mittelfristig wird Open API wohl zum neuen Standard in der API-Dokumentation heranwachsen, was die eh schon große Community sicherlich begrüßen wird.