Integration

API First mit Oracle Apiary umsetzen

Eine API-First Strategie bietet viele Vorteile

Noch vor einigen Jahren begann die Anwendungsentwicklung mit dem Design der Datenbankstrukturen und darauf aufbauend der Entwicklung der Businesslogik. Die Businesslogik wurde überwiegend auf einem Applikationsserver ausgeführt. APIs waren kein integraler Bestandteil der Applikation und wurden nur bei Bedarf konzipiert und hinzugefügt, wenn andere Systeme Zugriffe auf gespeicherte Daten benötigten. Die Entwicklung und Bereitstellung dieser APIs benötigte viel Zeit und Geld. Ferner orientiert sich das Design dieser APIs immer am konkreten Anwendungsfall. Das führte zu einer Vielzahl von unterschiedlichen APIs, wodurch die Wiederverwendbarkeit nicht automatisch sichergestellt war.

Eine neue Rolle für APIs

In der heutigen VUKA-Welt ist diese Vorgehensweise nicht mehr erfolgsversprechend. Wir leben in einer verteilten und schnelllebigen Welt. Um den vielen neuen Herausforderungen begegnen zu können, hat sich auch die Art und Weise, wie man Anwendungen baut, in den letzten Jahren verändert. Neue Architekturansätze, wie z. B. Microservices, sind entstanden und ermöglichen die schnellere Bereitstellung und horizontale Skalierung von Geschäftsfunktionen. APIs stellen die Schnittstelle für die Nutzung dieser Geschäftsfunktionen zur Verfügung. Fachliche Prozesse können durch Orchestrierung verfügbarer (Micro-)Services und APIs sehr gut abgebildet werden. Die Integration von Daten und Bereitstellung von neuen Diensten und Applikationen kann nur durch die Nutzung von APIs erreicht werden. Damit folgt, das die Anforderungen und Rahmenbedingungen an APIs, aus Sicht eines Konsumenten, enorm gestiegen sind. APIs, die nicht genutzt werden, sind wertlos! Aus diesem Grund, ist es notwendig, die Rolle von APIs im Rahmen der Anwendungsentwicklung neu zu definieren. Mit dem API First Prinzip werden den APIs eine ganz zentrale Rolle im Rahmen einer Anwendungsarchitektur zugestanden.

API first

API First bedeutet, dass alle Daten und Funktionen einer Anwendung über eine API angesprochen werden können. Idealerweise nutzt die Anwendung selbst ihre eigenen APIs. Als Konsequenz ergibt sich hierdurch die Notwendigkeit, APIs zu Beginn zu konzipieren und bereitzustellen.

Nutzung von APIs

Nutzung von APIs

 

Eine API-First Strategie bietet viele Vorteile:

  • Das Design der API ist auf Wiederverwendbarkeit und Developer Experience ausgerichtet, d.h. die API wird gerne und häufig benutzt.
  • APIs können frühzeitig durch Beispielimplementierungen (Mocks) bereitgestellt werden. Somit ist es nicht erforderlich auf die finale Implementierung der API zu warten. Potentielle Nutzer können mit der Beispielimplementierung arbeiten und Feedback geben. Somit wird die Kommunikation zwischen API-Anbieter und -nutzer aktiv gefördert. Notwendige Änderungen im API-Design können ohne Anpassung der Implementierung berücksichtigt werden, Entwicklungskosten werden eingespart.
  • Implementierungsdetails und Technologienfragen können in dieser frühen Entwicklungs-Phase ausgeblendet werden. Es erfolgt eine Fokussierung auf die fachlichen Anforderungen. Hierdurch entstehen fachlich orientierte und stabile APIs.
  • Die Entwicklung auf Seite des API-Bereitstellers und -konsumenten kann parallelisiert werden. Eine signifikante Verringerung der Entwicklungszeit wird erzielt.

Die Umsetzung einer API-First Strategie kann durch Werkzeuge optimal unterstützt werden. Nachfolgend wird die Umsetzung auf Basis vom Oracle API Platform Cloud Service erläutert.

Oracle API Platform Cloud Service

Der Oracle Service ermöglicht die Verwaltung von APIs über den gesamten Lebenszyklus vom Design bis zur Stilllegung.

API Lifecylce

API Lifecylce

Mit Apiary bietet die Oracle Plattform ein Werkzeug zum Design und Testen von APIs. Idealerweise kann mit Apiary eine API-First Strategie umgesetzt werden.

Basis für jede API ist eine Spezifikation. In der Spezifikation wird der Zweck, Rahmenbedingungen, die Funktionen und Daten im Detail beschrieben. Apiary erlaubt die Spezifikation nach API Blueprint oder Swagger 3.0 zu formulieren. API Blueprint ist eine Sprache auf Basis von Markdown und somit sehr gut lesbar.

API Blueprint

Aufbau API Blueprint

Aufbau API Blueprint

Die Spezifikation API Blueprint ist ein hierarchisches aufgebautes Format und unterteilt in verschiedene Sections. Eine Resource wird in einer sog. ResourceGroup beschrieben. Die Beschreibung zu einer Resource enthält Angaben zu Parametern, Attributen und natürlich den Actions, die auf eine Resource operieren können.

Zu einer Action werden insbesondere der Aufbau von Request und Response Messages beschrieben. Die Beschreibung kann unterschiedliche Varianten und Sonderfälle enthalten. Auf Basis der Definition der Resource können die Funktionen über einen Mockservice aufgerufen werden.

API Design testen (Mock)

Apiary stellt einen Mock für die definierte API zur Verfügung. Die URL für den Aufruf des Mockservices wird direkt in Apiary angezeigt. Der Tests des Mockservices kann beispielsweise in SoapUI erfolgen.

Mockservice Definition in Apiary

Mockservice Definition in Apiary

 

 

Testen eines Mockservices in SoapUI

Testen eines Mockservices in SoapUI

Mit dem Mockservice können dann auch potentielle Nutzer des Service angehalten werden, die API zu testen, Fragen zu stellen und Feedback zu geben. Das ermöglicht eine schnelle Anpassung, noch bevor eine einzige Zeile Code für den Service geschrieben wurde.

Apiary versioniert die Beschreibung einer Resource nicht. Allerdings wird eine bi-direktionale Synchronisation mit GitHub zur Verfügung gestellt. Die Integration ermöglicht die Versionierung einer API-Definition. Nach einer Änderung und einem commit in GitHub erfolgt eine automatische Synchronisation nach Apiary. Umgekehrt werden Änderungen in Apiary sofort nach GitHub übertragen. Somit können unterschiedliche Versionen einer API-Definition verwaltet und getestet werden.

Zunächst muss Apiary mit einem Repository in GitHub verbunden werden (siehe nachfolgender Screenshot)

Integration GitHub und Apiary

Integration GitHub und Apiary

 

Danach kann eine API-Definition sowohl in Apiary, als auch direkt in GitHub bearbeitet werden. In den zwei nachfolgenden Screenshots ist die Arbeitsweise skizziert.

GitHub -> Apiary

Apiary -> GitHub

 

Sonstiges

  • Zusätzlich gibt es weitere interessante Funktionen in Apiary, die ich eventl. in zukünftigen Blogeinträgen erläutern werde: API Design Styleguide erstellen und prüfen
  • Automated Testing und Abgleich der Definition mit der aktuellen Implementierung
  • Integration der API-Definition in Apiary mit dem Developer Portal

Referenzen