Warum benötigen REST-APIs eine Dokumentation?

Eine gut gelungene REST-API zeichnet sich durch unterschiedliche Qualitätsmerkmale aus. Hierzu gehören: Konsistenz, einfache Benutzbarkeit und geeignete Abstraktion. Aber auch eine ordentliche Dokumentation darf dabei nicht fehlen. Schließlich soll die API ja auch für andere Entwickler verständlich und benutzbar sein.

Bevor man mit der Implementierung einer App beginnt, ist es also ratsam, sich über den Aufbau der API Gedanken zu machen. Nur so lassen sich Schwachstellen frühzeitig erkennen und beheben.

Mittlerweile gibt es diesbezüglich eine ganze Reihe verschiedener Formate und Tools, die das Planen, Entwerfen und Dokumentieren von Tools erleichtern bzw. unterstützen. Die bekanntesten sind: RESTful API Modeling language (kurz: RAML), API Blueprint, Open API (auch bekannt als Swagger) und APIDOC.

Dieser Blogbeitrag widmet sich dem Open-Source-Framework „Swagger“. Nach einer kurzen theoretischen Einführung und einen Einblick in die Entstehungsgeschichte, werden wir anhand einer Demospezifikation schrittweise erörtern, wie Swagger in der Praxis funktioniert.

Allgemein

Swagger (http://swagger.io) gehört neben RAML und API-Blueprint zu den meist verwendeten Formate zur Spezifikation von REST-APIs. Swagger bietet ein sprachneutrales und maschinenlesbares Format und wird von vielen Tools erkannt und unterstützt. Das Toolset von Swagger bietet einige praktische Features wie beispielsweise: automatisiertes Dokumentieren, Code-Generierung und Testfallgenerierung. Als Auszeichnungssprache können sowohl YAML aus auch JSON verwendet werden.

YAML

YAML ist eine Auszeichnungssprache zur Serialisierung großer Mengen von JSON-Daten. Das Akronym YAML steht für „YAML Ain’t Markup Language“. YAML ist leichter von Menschen zu lesen und zu schreiben als beispielsweise JSON oder XML.

Geschichte

Das Swagger-API-Projekt wurde 2011 von Tony Tam in’s Leben gerufen. Im Rahmen seiner Tätigkeit als Software-Architekt erkannte er die Notwendigkeit einer automatisierten API-Dokumentation. Denn eine reine Sammlung von URLs reichte als Dokumentation nicht aus und ein einfaches, unkompliziertes Beschreibungsformat existierte bis dato noch nicht. Vor allem aber die Verwendung unterschiedlicher Technologien und Programmiersprachen in Kombination mit WSDL (Web Service Descriotion Language) und WADL (Web Application Description Language) erwies sich als äußerst schwierig.  Daraufhin wurde Swagger entwickelt: eine IDL (Interface Definition Language) für REST-APIs und als Open Source Projekt veröffentlicht.              

Die Demospezifikation „Petstore“

Eine fertige Demonstration einer API-Dokumentation ist der sogenannte Petstore. Diesen finden wir unter: http://petstore.swagger.io/#/

Noch besser ist allerdings die Verwendung des Online Editors. Unter http://editor.swagger.io können APIs mithilfe eines „Live-Editors“ entworfen werden. Der Vorteil dieses Editors ist, dass parallel zum YAML-Code eine interaktive Swagger-HTML-Dokumentation entsteht, wie in folgender Abbildung ersichtlich.

• 

Eine Swagger-Spezifikation beginnt immer mit Metainformationen wie: Spezifikationsversion, gefolgt von generellen Informationen zur API im Abschnitt Info. Host, Pfad und das URL-Schema werden in eigenen Variablen darunter angegeben.

swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
- name: "pet"
  description: "Everything about your Pets"
  externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
- name: "store"
  description: "Access to Petstore orders"
- name: "user"
  description: "Operations about user"
  externalDocs:
    description: "Find out more about our store"
    url: "http://swagger.io"
schemes:
- "https"
- "http"

Ebenso hier zu finden ist auch die Sektion „Tags“. Damit können wir eine Liste mit allen implementierten Ressourcen und dazugehörigen Operationen erstellen. In unserem Fall beginnt diese Sektion mit der Ressource „pet“. Ein kurzer Blick darauf verät uns, was mit dieser Ressource alles geschehen kann: Sie kann gespeichert (POST), aktualisiert (PUT), abgerufen (GET) und natürlich auch gelöscht werden (DELTE).

Der eigentliche Teil der Dokumentation beginnt jedoch erst mit dem Abschnitt ,,paths“. Hier werden die eigentlichen Inhalte dargestellt: Pfade, Operationen, Parameter sowie die dazugehörigen Antworten einschließlich ihrer Beschreibung. Datentypen werden wiederverwendbar in einem Abschnitt definitions verwaltet. Ebenso wird für die gesamte API der Mediatyp (produces/consumers) festgelegt.

paths:
  /pet:
    post:
      tags:
      - "pet"
      summary: "Add a new pet to the store"
      description: "Here we can add a pet"
      operationId: "addPet"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Pet object that needs to be added to the store"
        required: true
        schema:
          $ref: "#/definitions/Pet"
      responses:
        405:
          description: "Invalid input"
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"

Sehen wir uns nun obigen Code, also den Pfad „pet“ mit der Operation „post“ etwas genauer an, um zu verstehen, was die einzelnen Elemente bedeuten. Schon am ersten Blick sehen wir sehr gut die hierarchische Abbildung durch die Einrückungen.

• Das Snippet beginnt mit der „post–Deklaration“ also jener http-Operation die zum Speichern, Erstellen und Weiterverarbeiten von Daten verwendet wird. Der gesamte folgende Code der sich durch die Einrückung hierarchisch darunter gliedert, betrifft logischerweise diesen Befehl.
• Danach wird diese Operation dem Tag „pet“ zugeordnet. Durch diese Zuweisung werden wir den nachfolgenden Code auch in unseren Tags (wir vorhin erläutert) finden.
• Danach finden wir eine Zusammenfassung (summary) und eine Beschreibung (description) über jene Operation vor.
• Die operationId dient zur eindeutigen Adressierung und als mögliche Referenz für lokale Links.
• consumes und produces dienen zum Festlegen sogenannter MIME-Types. Eine API kann Daten in verschiedenen Formaten annehmen und zurückgeben. Die häufigsten sind JSON und XML, wie auch in diesem Fall.
• Parameter: Das Parameterobjekt beschreibt die einzelnen Parameter, die in einer Operation gesendet werden sollen, und bildet somit das Operationsobjekt ab.
• Responses: Hier werden die Rückgabewerte nebst Fehlercode festgelegt.
• Im Abschnitt security werden Berechtigungen definiert.

Das sind jetzt nur einige wichtige Funktionen von Swagger. Natürlich umfasst die Swagger-Spezifikation noch viel mehr Funktionen, auf die aber hier nicht bis ins Detail eingegangen werden soll. Dafür bietet sich die Dokumentation an: https://swagger.io/docs/specification/about/

API-Endpunkte

Wer künftig seine APIs mit Swagger dokumentieren will, benötigt ein Verständnis dafür wie man sogenannte Endpunkte definiert. Sie bilden schließlich das Herzstück einer Dokumentation. Ein Endpunkt ist eigentlich nichts anderes als eine Operation die von einem Benutzer ausgeführt wird.

Auch in unserem Petstore finden wir eine Reihe verschiedener Benutzeroperationen in Form von Pfaden.

Dazu einige Beispiele:

/pets/{petId}/(get)	Ermöglicht es, die Ressource Pet über eine Id zu finden
/pet/findByStatus/(get)	Ermöglicht es, ein Pet über einen Status zu finden
/pet(post)	Fügt dem Store ein neues Pet hinzu
/pet(put)	Ermöglicht es, ein bestehendes Pet zu aktualisieren
/pet(delete)	Löscht ein vorhandenes Pet

Innerhalb dieser Endpunkte werden mögliche Antwortnachrichten spezifiziert. Die Antwortnachricht mit einem Statuscode von beispielsweise 404 referenziert die globale Definition für das Pet-Datenmodell das die Fehlermeldung „Pet not found“ zurückliefert. Eine Antwortnachricht mit dem Code 200 hingegen, referenziert die die globale Definition, die ein bestimmtes Pet zurückliefert. (siehe nachfolgendes Listing)

paths:
  /pets/{petId}:
    get:
      tags:
        - pet
      summary: Find pet by ID
      description: Returns a pet
      produces:
        - application/json
      parameters:
        - in: path
          name: petId
          description: ID of pet that needs to be fetched
          required: true
          type: integer
          format: int64
      responses:
        "200":
          description: successful operation
          schema:
            $ref: "#/definitions/Pet"
        "400":
          description: Invalid ID supplied
        "404":
          description: Pet not found

So lassen sich mit Swagger httpbasierte APIs sehr gut abbilden.

Die interaktive Swagger-HTML-Dokumentation

Der nachfolgende Screenshot zeigt einen Ausschnitt der interaktiven Swagger-HTML-Dokumentation. Was auf den ersten Blick sehr übersichtlich und anschaulich aussieht, birgt noch große Verbesserungspotentiale. So liegt beispielsweise der Schwerpunkt dieser Visualisierung auf den API-Endpoints, nicht aber auf einer Funktionsbeschreibung, die jedoch von großem Nutzen wär. Wenn nun also ein Benutzer die API noch nicht kennt, und nach einer bestimmten Funktion sucht, wie bspw. deletePetById(), würde er nicht nach dem passendem Endpoint suchen, sondern nach der gewünschten Funktionalität.

Ein weiteres Manko ist der fehlende PDF-Export. In vielen Fällen wird man die Doku auch im PDF-Format benötigen – beispielsweise bei Projektabnahme oder für den Fall dass bei einer Ausschreibung auch eine Doku mitgeliefert wird.

Nichtsdestotrotz: Swagger ist noch immer ein relativ junges Framework, das laufend weiterentwickelt wird. Swagger UI und alle anderen Swagger-Tools sind kostenfrei und Open Source. Zudem hat sich Swagger auch sicher nicht zufällig zu einem der Marktführer gekämpft. Ich bin zuversichtlich, dass Swagger auch in den kommenden Jahren eine wichtige Rolle im Bereich der Software-Dokumentation spielen wird.