API Design & OKRs

Neben anderen Schlagwörtern, wie z. B. Software-as-a-Service (SaaS) gibt es heutzutage auch den Begriff API-as-a-Product (AaaP). So werden APIs wie jedes andere Produkt behandelt. Dies gilt es in jedem Schritt entlang des Lebenszyklus zu beachten, sei es beim Design, bei der Implementierung eines Prototyps oder auch zur Laufzeit. Deshalb ist es wichtig zu verstehen, welche Entscheidungen und Faktoren wichtig sind, um den Erfolg einer API zu gewährleisten. 

API Strategie 

„Great products start with a great strategy, and API products are no different.“ (Medjaoui et al. 2018, S. 60)

Neben anderen Schlagwörtern, wie z. B. Software-as-a-Service (SaaS) gibt es heutzutage auch den Begriff API-as-a-Product (AaaP). Ich habe euch davon schon berichtet. So werden APIs wie jedes andere Produkt behandelt. Dies gilt es in jedem Schritt entlang des Lebenszyklus zu beachten, sei es beim Design, bei der Implementierung eines Prototyps oder auch zur Laufzeit. Deshalb ist es wichtig zu verstehen, welche Entscheidungen und Faktoren wichtig sind, um den Erfolg einer API zu gewährleisten. 

Ein Produkt muss immer ein menschliches Bedürfnis erfüllen bzw. ein vorhandenes Problem lösen, sofern es Akzeptanz erhalten soll. Dieses Kriterium muss auch eine API erfüllen, damit sie von ihren Nutzern angenommen wird. Gerade beim Design entsteht damit eine Vielzahl an Aufgaben. Der Fokus sollte darauf liegen, was der Kunde oder Nutzer braucht und noch vielmehr, wer die Gruppe an Nutzern überhaupt ist, um die API möglichst zielgenau auf den Kundenkreis abzustimmen und somit die Akzeptanz zu erhöhen (Vgl. Medjaoui et al. 2018, S. 39– 41).

Umsetzung mit OKRs

Daher müssen zunächst Ziele für ein Unternehmen definiert und beschrieben werden. Dann kann entschieden werden, wie die API dabei helfen soll, diese zu erreichen. Damit wird die API zu einem Produkt, die zum Wert eines Unternehmens beiträgt, indem sie das Voranschreiten der taktischen Maßnahmen unterstützt. Aus diesem Grund ist die Strategie für eine API auch immer abhängig von der Strategie eines Unternehmens, da sie in gewisser Weise das Aushängeschild für Software innerhalb der Anwendungslandschaft ist, also das was ein Kunde oder Entwickler von der Software zuerst sehen kann. Doch dies lässt sich auch für interne APIs adaptieren. Der Nutzer muss nicht zwangsläufig ein externer Kunde sein, sondern kann dieselben Bedürfnisse auch intern haben (Vgl. Medjaoui et al. 2018, S. 60–61).

Um Ziele und Meilensteine, die man sich auferlegt auch messbar zu machen, sei es den Wert, oder auch die Qualität, ist es sinnvoll sogenannte key performance indicator (KPI) zu formulieren. Mit ihnen ist es dann einfacher zu beschreiben, wie gut oder schlecht sich ein Faktor im Vergleich zum gesetzten Ziel verhält. Die Wahl der richtigen KPIs ist entscheidend, um den Fortschritt zu messen. Kritische Erfolgsfaktoren müssen identifiziert werden. Eine nützliche Methode ist die Formulierung sogenannter OKRs (objectives, key results), mit deren Hilfe man Ziele („objectives“) und die daraus resultierenden Maßnahmen („key results“) identifizieren kann, die es braucht, um die beschriebenen Ziele zu erreichen. Beispielhafte „API objectives“ könnten die Aufrufe der API für einen bestimmten Zeitraum oder der prozentuale Anstieg der Verkäufe einer Software sein (Vgl. Medjaoui et al. 2018, S. 106–108).

API Design

Dieser Satz lässt die Relevanz des API Designs schon erahnen. Soll die API genutzt werden, muss sie den Bedürfnissen der Nutzer entsprechen. Sie muss zur Lösung eines vorhandenen Problems beitragen und die Anwendungsfälle innerhalb eines Geschäftsvorfalls realisieren, damit sie Akzeptanz sowohl im Unternehmen als auch von den Kunden erfahren kann (Vgl. Medjaoui et al. 2018, S. 61).

Die Einhaltung der technischen Vorgaben ist durch Standards, wie z. B. bei SOAP, oder zumindest durch Richtlinien, wie bei REST leicht einzuhalten. Bei REST werden Ressourcen durch URIs identifiziert, welche immer die Ressource direkt adressieren und nicht Methoden. CRUD-Operationen werden durch HTTP Methoden umgesetzt, das Protokoll ist dabei ebenfalls HTTP. Die Überprüfung zur Einhaltung dieser Vorgaben ist wichtig, aber auch einfach umzusetzen. 

Die Sicherstellung, dass eine Schnittstelle fachlich ansprechend und für Anwender nützlich designt ist, kann nicht nach solchen Standards etabliert werden. Ziele und deren Anwendungsfälle müssen daher klar beschrieben sein, um sicherstellen zu können, dass die API diesen entspricht bzw. diese realisiert. Genauso wichtig ist es aber auch, die Ziele regelmäßig zu überprüfen, denn auch diese können sich ändern, oder sogar ganz wegfallen (Vgl. Medjaoui et al. 2018, S. 115–116).

Die OpenAPI Specification

Ist die API designt, so folgt die Dokumentation dieser. Für die Dokumentation einer API gibt es eine Vielzahl an Möglichkeiten für Werkzeuge und verschiedene Spezifikationsformate. Unterschieden wird dabei zwischen einer fachlichen und einer technischen Dokumentation. 

Die fachliche Dokumentation soll die API für die Geschäftsseite der Konsumenten verständlich erklären. Hierbei sollen alle relevanten Geschäftsobjekte und Geschäftsfunktionen aufgeführt werden, die die API bereitstellt. Dabei ist es ebenfalls möglich den Zusammenhang zu der technischen Spezifikation herzustellen. 

Die technische Spezifikation wiederum stellt den API-Kontrakt im eigentlichen Sinne dar. Ihr können Entwickler, die an der Schnittstelle Applikationen anknüpfen wollen, die dafür relevanten Informationen entnehmen. Beispiele wären die „Endpoints“ einer API, also die Ressourcen, die mit der API angesprochen werden können, genauso die möglichen HTTP-Methoden, die darauf angewendet werden können.

Als Spezifikationsformat für die API wird die OpenAPI Specification 3.0 des Swagger Frameworks empfohlen. Wenngleich es hier eine Vielzahl an Frameworks gibt, wie z. B. RAML oder API Blueprint. Diese Frameworks sind alle ähnlich gut bewertet und liefern nahezu dieselben Funktionen (Vgl. De 2017, S. 78–79). Swagger liefert hier zusätzlich zu der Auszeichnungssprache noch eine Reihe an Tools, wie Swagger UI und den Swagger Editor, um die API zum einen grafisch aufbereitet anzuzeigen und zum anderen direkt im Editor zu verändern.

Die fachliche Dokumentation beläuft sich hauptsächlich auf textuellen Inhalt. Hierbei liegt es häufig nahe Word-Dokumente zu schreiben, welche dann im PDF-Format verteilt werden. Die Entscheidung gegen Word lässt sich allerdings gut begründen. Zum einen arbeiten meist mehrere Personen an dieser Dokumentation, Versionierung ist hierbei nur schwer möglich. Zum anderen sollen auch fachliche Dokumente im Netz veröffentlicht werden. Gerade wenn Developer Portale angeboten werden, lässt sich das Verständnis stärken, wenn fachliche Dokumente auch dort eingesehen werden können. Diesen Ansprüchen können solche Textdokumente nicht gerecht werden, weshalb es sich empfiehlt AsciiDoc oder Markdown zu verwenden. 

Diese Formate können in gängige Formate, wie HTML oder auch PDF konvertiert werden, sofern es dessen bedarf. Außerdem ist es möglich, die Dateien in einem Git-Repository zu verwalten und zu versionieren, um so parallele Arbeiten daran zu ermöglichen.

Ich hoffe der Beitrag hat euch gefallen. Wie immer sind Feedback und Rückfragen erwünscht. Gebt uns gerne Bescheid!

Quellen:

De, Brajesh (2017): API Management. An Architect's Guide to Developing and Managing APIs for Your Organization. New York City: Apress Media LLC. 

Massé, Mark (2012): REST API Design Rulebook. Designing Consistent RESTful Web Service Interfaces. Sebastopol: O'Reilly Media Inc.

Medjaoui, Mehdi; Wilde, Erik; Mitra, Ronnie; Amundsen, Mike; Lane, Kin (2018): Continuous API Management. Making the right decisions in an evolving landscape. Sebastopol: O'Reilly Media Inc.

Swagger authors (2020): OpenAPI Specification 3.0.3. Hg. v. Swagger.

zuletzt geprüft am 02.05.2019.