Wie eine Dokumentationsnotation REST erwachsen werden lässt

Einstieg in OpenAPI v3: REST wird erwachsen
Keine Kommentare

Wir sind bis vor einigen Jahren in Workshops und Coachings zum Thema REST im Architekturumfeld oft mit der Frage konfrontiert worden, weshalb es nicht so etwas Tolles wie WSDL im REST-Umfeld gibt. Diese Frage hat immer ein Kopfschütteln ausgelöst.

Die Frage ist zwar berechtigt, aber im Umfeld von (REST-)APIs galten damals technische Dokumentationen immer schon als ungeliebtes Kind. Zu groß war die Angst davor, dass um die REST-Thematik auf Kosten der Entwickler-UX herumspezifiziert wird. Erinnerungen an diverse SOA-Projekte aus der Vergangenheit wurden bei diesen Diskussionen geweckt, inklusive des damals noch etwas anderen Kontexts:

  • Single Purpose Integration mit SOAP-Schnittstellen statt wiederverwendbare APIs (für einen dezidierten Abnehmer eine Schnittstelle auf ein Legacy-System „draufpacken“).
  • Per E-Mail verschickte, teilweise nicht mehr zum Produktionsstand passende WSDLs und unvollständig verfasste Dokumentationen (in Word-Format).
  • Nicht transparente Versionierungs- bzw. Abkündigungsstrategie (Stichwort: Deprecation und Sunsetting) konnte man sich bei Single-Purpose-Integrationen meist sparen.
  • Organisatorisch bedingte Motivationsprobleme und Kommunikationsbarrieren, da Budgettöpfe zu selten über Abteilungsgrenzen hinweg aufgemacht wurden oder der externe Consultant als technischer Schnittstellen-Owner für ein zugekauftes Fremdsystem schwer erreichbar war.

Vieles hat sich seitdem verändert. Die Ideologie hinter webbasierten Diensten hat sich aufgrund von Multichannel-Strategien (Mobile-Apps, IoT Gadgets, JavaScript Frontends) massiv verändert. Der Stellenwert der externen Cliententwickler ist stark in den Vordergrund geraten.

Wer früher als pixelschubsender JavaScript-Entwickler belächelt wurde, kombiniert heutzutage die unterschiedlichsten Fremd-APIs in Form eines modernen Frontends zu einem neuen Geschäftsmodell. Innovative Firmen, egal ob Onlinegiganten oder Start-ups, haben mit ihrer gefürchteten Rolle als Disruptoren ein neues Marktsegment geschaffen: die API Economy. Wer kein API hat oder den Aufwand für die Integration scheut, wird im schlimmsten Fall aus dem neuen System ausgeschlossen und erleidet ggf. wirtschaftliche Nachteile.

Technische Schnittstellen sind seitdem keine „Friss oder Stirb“-Angelegenheit mehr, sondern werden von Evangelisten vermarktet. Es werden Hackathons als Recruiting- und Vermarktungsstrategie abgehalten. Selbst die Erwartungshaltung von intern beschäftigten Entwicklern ist sehr hoch, da der Großteil der in der Freizeit getriebenen Projekte auf Drittanbieter-APIs basiert bzw. erfolgreiche Open-Source-Projekte neue Maßstäbe bzgl. der Qualität der Dokumentation gesetzt haben.

Zurück zur Fragestellung: Bisherige Schnittstellenkonzepte wie z. B. SOAP/WSDL oder EDI spielen aufgrund der Entwickler-UX zunehmend eine untergeordnete Rolle. Welcher Angular-, Android- oder iOS-Entwickler hat Lust auf, geschweige denn versteht eine kilometerlange XML-Dokumentation? Wen frage ich, wie ich mit einem der vielen WS-*-Standards – auch häufig als WS-Todesstern bezeichnet – umgehen soll?

Wie beschrieben hat sich in der Zwischenzeit der Stellenwert von Web-APIs aufgrund der genannten API-Economy-Initiativen drastisch gewandelt. Meist wird ein Mittelweg zur Beschreibung eines API gesucht, der sowohl Entwickler als auch Architekten zufriedenstellt. Eine Dokumentationssprache sollte folgende Aspekte ermöglichen:

  1. Die Beschreibungssprache ist einfach zu erlernen und zu lesen.
  2. Ein starkes Tool-Ecosystem (Editor, Codegenerator, Testwerkzeuge) ist vorhanden.
  3. Es ist möglich, ein API vollständig technisch zu spezifizieren.
  4. Die Sprache erlaubt es, ein API fachlich zu dokumentieren.
  5. Alles zuvor Genannte soll möglichst entwicklerfreundlich sein, um niedrige Einstiegshürden zu gewährleisten.
  6. Es gibt eine Möglichkeit, aus der Dokumentation heraus live das API zu erforschen und Beispiel-Requests abzuschicken.

Ironischerweise hat sich mit der Swagger Specification vor einigen Jahren eine zuerst proprietäre Dokumentationssprache durchgesetzt, die viele Bedürfnisse aus Architektur- und Entwicklersicht erfüllt: Swagger ist einfach zu schreiben, verfolgt den Contract-First-Gedanken, ist sehr nah an der Denkweise von REST/HTTP, hat erstklassigen Dokumentationscharakter und ein immens großes und wachsendes Ökosystem mit Tools und Generatoren.

Mit der aktuell geltenden Version 2 der Swagger Specification waren allerdings einige Dinge nicht machbar, die wesentlicher Bestandteil der „RESTafarian Orthodoxy“ sind. Hier sei erwähnt, dass die Thematik REST für viele Entwickler und Architekten seit langer Zeit einen Religionscharakter angenommen hat. Dementsprechend hitzig wird über diverse Konzepte seit Jahren diskutiert.

Im November 2015 wurde die Swagger Specification in Version 2 vom Toolhersteller SmartBear (bekannt durch SoapUI) an die Linux Foundation übergeben und trägt seitdem den Namen OpenAPI Specification. Die dazugehörigen Tools behielten allerdings den Namensteil „Swagger“. Seit diesem Zeitpunkt ist sie im Umfeld der API-Spezifikation im Mainstream angekommen.

Vielen war klar, was jetzt passieren würde bzw. müsse: Große Unternehmen und Hersteller von Testwerkzeugen, API-Management-Plattformen und Gateways haben sich auf die Spezifikation gestürzt und wichtige fehlende Bausteine zusammen mit der Community nachspezifiziert. Die OpenAPI Specification v3 wurde im Juli veröffentlicht.

Besondere Änderungen

Betrachten wir eine Zusammenfassung der wichtigsten Neuerungen in OpenAPI v3. Zur Verdeutlichung der strukturellen Änderung sollte ein Blick auf Abbildung 1 geworfen werden.

Die oberflächliche Struktur wurde massiv bereinigt. Dabei wurde auch ein großes Augenmerk auf die Wiederverwendbarkeit von spezifizierten Elementen gelegt.

Abb. 1: Vergleich openAPI 2.0 versus openAPI 3.0.

Abb. 1: Vergleich openAPI 2.0 versus openAPI 3.0. Quelle

Im Folgenden betrachten wir die Änderungen im Einzelnen und kommentieren ihre Bedeutung für die Zukunft.

Wiederverwendbare Komponenten: In der bisherigen Version war es bereits möglich, den Aufbau der Nutzdaten, Standard Responses und Parameter wiederverwendbar zu deklarieren. Allerdings geschah dies in unterschiedlichen Bereichen innerhalb der API-Dokumentation (Definitions für Objekte, Responses für Standardantworten usw.). Hier findet in Version 3 eine massive Umstrukturierung zugunsten der Übersichtlichkeit statt. Im neuen Bereich Components können nun wiederverwendbare Securitykonfigurationen, Requests, Responses, Parameter, Objektschemata und Beispiele, HTTP-Header, Links und Callbacks in einem zentralen Container definiert werden.

Serverspezifikation: Bisher war es nur möglich, einen Server/Host zu spezifizieren. Praxisrelevante Konfigurationen mit z. B. mehreren Stages (Demo/Development/Production) und Stage-abhängigen Eigenschaften (unterschiedliche Basis-URLs/Basispfade/Ports etc.) konnten so nur schwer dargestellt werden. In der neuen Version ist es nun möglich, mehrere Server/Hosts auf Basis eines Templatemechanismus zu definieren und ggf. per Extension-Mechanismus Stage-Variablen und -eigenschaften zusätzlich zu spezifizieren. Server können nun global, auf Ressourcen-, Pfad- oder Operationsebene definiert werden.

Security mit besserem OAuth- und OpenID-Connect-Support: In der OpenAPI-v2-Spezifikation war es bereits möglich, zwischen HTTP und HTTPS zu unterscheiden und rudimentär zu definieren, ob der Zugriff z. B. per Basic Authentication oder OAuth erfolgen soll. OpenAPI v3 macht auch hier einen deutlichen Sprung nach vorn und ermöglicht die vollständige Dokumentation der gängigen Securitykonzepte im Umfeld der API Security (Basic Authentication, API Keys, OAuth2, OpenID Connect). Neben dem gewählten Verfahren lassen sich auch die diversen Flows, URLs, Scopes und Hinweise bzgl. des Bearer-Tokens (z. B. JSON Web Tokens) hinterlegen. Nun können auch multiple Securitykonfigurationen global definiert und feingranular auf einzelne Operationen innerhalb eines Pfads abgebildet werden.

Content Negotiation: Ein großer Streitpunkt in der REST-Community war bisher die fehlende Unterstützung für eine vollumfängliche Content Negotiation. Viele API-Anbieter erlauben den Abruf von Ressourcen in unterschiedlichen Repräsentationen (XML, JSON). Sowohl unterschiedliche Formate als auch unterschiedliche Strukturen können mit diesem wichtigen REST-Prinzip verhandelt werden.

Darüber hinaus wird eine Versionierung häufig auf Repräsentationsebene über den MIME Type realisiert. In der Regel ändert sich im Laufe der Zeit nur die Objektstruktur, während das Ressourcendesign normalerweise stabil bleibt. Zu diesem Zweck werden in der Praxis Vendor-spezifische MIME Types verwendet, beispielsweise application/vnd.ars.products.v3+json oder application/vnd.ars.products+json; version=3. Erfreuliche Nachricht: In der neuen OpenAPI-Version lässt sich endlich auch eine Content Negotiation mit unterschiedlichen Repräsentationen und Strukturen abbilden.

Ausbau des JSON Schema Supports: Die Spezifikation wiederverwendbarer Artefakte erfolgt nun auf Basis eines erweiterten Subsets des „JSON Schema Specification Wright Draft 00“ (auch als Draft 05 bekannt). Praktische Schlüsselwörter wie oneOf, anyOf, not, nullable, deprecated, writeOnly gehören nun zum Wortschatz. Wichtig zu erwähnen ist, dass einige Bestandteile aus der JSON-Schema-Spezifikation allerdings bewusst weggelassen wurden und gleichzeitig einige Properties innerhalb der OpenAPI-Spezifikation aus guten Gründen anders angewendet werden müssen. Die genaue Verwendung von JSON Schema wird in der Dokumentation erfreulicherweise prägnant und gut verständlich behandelt.

Links und Callbacks: In OpenAPI v3 ist es nun möglich, Links in der Dokumentation sauber zu beschreiben. Ein sehr ausgeklügelter Templatemechanismus ermöglicht die Beschreibung von Abhängigkeiten der Links zu einzelnen Parametern innerhalb der empfangenen Nachricht (z. B. IDs, Namen, Timestamps usw.). Auch Query-Parameter für den Folge-Request können gesetzt werden. Dies ist als erster Schritt in Richtung HATEOAS (Hypermedia As The Engine Of Application State) zu betrachten. Allerdings werden hier nur die statischen Zusammenhänge in der Dokumentation abbildbar, während HATEOAS ein Laufzeitkonzept ist. Das API liefert demnach immer eine Menge von Links für mögliche Zustandstransitionen des Clients. Auch Folgeoperationen nach einer erfolgreichen Verarbeitung, sogenannte Callbacks bzw. Webhooks, können spezifiziert werden.

Offene Baustellen

Die Dokumentation von Web-APIs gehört mittlerweile zum guten Ton. Alle sind sich über die Wichtigkeit dieser Disziplin einig, und es gibt mit der OpenAPI Specification v3 nun auch einen vollständigen und brauchbaren Standard in diesem Umfeld. Durch den Einsatz einer nahezu vollständigen Beschreibungsnotation, abgesehen von einigen Abweichungen zum aktuellen JSON Schema Draft, werden Fragestellungen im Umfeld eines APItekten[1] auf technischer Ebene befriedigt, während auch weiterhin API-Designer und -Entwickler mit den wertvollen Dokumentationsfeatures und Werkzeugen aus dem OpenAPI- und Swagger-Universum mit einer guten Entwickler-UX belohnt werden.

Die Vervollständigung ermöglicht nebenbei auch eine dringend notwendige Verbesserung der Qualität von Generatoren und Werkzeugen (API-Management, Gateway-Integration, Integration in Developer-Portale, Client/Server-Generatoren, Test- und Mock-Generatoren). Es bleibt aber auch abzuwarten, wie lange es dauern wird, bis OpenAPI v3 tatsächlich von allen proprietären Toolherstellern adoptiert, bzw. auch die Zeit in bestehenden Projekten gefunden wird, um sich auf die neue Version der Spezifikation einzulassen. Vermutlich werden einige Open-Source-Frameworks (vor allem im npm/Node.js-Universum) aufgrund mangelnder Communityunterstützung wieder von der Bildfläche verschwinden. Diese Bereinigung ist aber eher als sinnvolle Konsolidierung zu sehen, da einige Frameworks nie über das Betastadium herausgewachsen sind und derzeit für diverse Anwendungsfälle teilweise mehrere von der Grundidee identische Frameworks existieren.

Anhand der Erhebung der Versionsnummer nach dem Prinzip des Semantic Versioning wird auch für den Laien sichtbar, dass dieser Sprung viele nicht abwärtskompatible Änderungen beinhaltet. Im Klartext bedeutet das zusätzliche Aufwände bzgl. Neudokumentation der internen oder öffentlichen Schnittstellen. Trotz der zusätzlichen Arbeit bleibt jedoch die Freude, dass ein lang andauernder Kampf vorerst ausgefochten ist. Man sollte allerdings nie den Zweck der Spezifikation vergessen. Die OpenAPI-Spezifikation ist:

  • ein Werkzeug zur Unterstützung im Entwicklungszyklus (Contract-First-Ansatz, Dokumentation, Spezifikation, Generatoren, Testing)
  • sehr gut geeignet für öffentliche APIs (während sich für interne APIs ggf. der Ansatz rund um das Pact-Framework anbietet)
  • kein Ersatz für eine HATEOAS-basierte Laufzeitdokumentation.

Platz für Diskussionen zwischen Skeptikern und Fanatikern dieses Ansatzes gibt es demnach weiterhin in ausreichender Form.

Links & Literatur

[1] An dieser Stelle ein Dankeschön an Gernot Starke und Peter Hruschka für die neu beschriebene Architekturrolle des APItekten: https://jaxenter.de/knigge-softwarearchitekten-api-55316

Unsere Redaktion empfiehlt:

Relevante Beiträge

X
- Gib Deinen Standort ein -
- or -