© stas11/Shutterstock.com
Entwickler Magazin
Wie eine Dokumentationsnotation REST erwachsen werden lässt

Einstieg in OpenAPI v3

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.

Stefan Sauterleute, Michael Heiß, Christopher Köster


Video: Die OpenAPI Specification aka Swagger – mehr als nur Schnittstellenbeschreibung

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 wiederverwendbarer 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.

Entwickler Magazin
Wie eine Dokumentationsnotation REST erwachsen werden lässt

Einstieg in OpenAPI v3

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.

Stefan Sauterleute, Michael Heiß, Christopher Köster


Video: Die OpenAPI Specification aka Swagger – mehr als nur Schnittstellenbeschreibung

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 wiederverwendbarer 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.

Neugierig geworden?


   
Loading...

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang