Die Integration von Softwaresystemen stellt seit vielen Jahren eine wiederkehrende Herausforderung für Entwickler dar. Und daran wird sich auf absehbare Zeit auch nichts ändern – eher im Gegenteil. Lediglich die technologischen Ansätze ändern sich. Aktuell gelten HTTP-basierte Schnittstellen als ein beliebtes Mittel. Das HTTP-Protokoll wird praktisch überall unterstützt und bietet viele Vorteile gegenüber proprietären oder ausgefalleneren Protokollen. Zudem kann die bestehende Infrastruktur des Webs somit auch für Integrationslösungen verwendet werden. Für den Austausch von Daten kommt dabei zumeist das JSON-Format zum Einsatz. Im Sprachgebrauch haben sich die Bezeichnungen Web-API, HTTP-API oder schlicht API eingebürgert, auch wenn letzterer Begriff natürlich eigentlich viel allgemeingültiger ist. Werden zusätzlich die Empfehlungen des REST-Ansatzes eingehalten (und nur dann), handelt es sich um eine REST-API.
Solche HTTP-basierten APIs lassen sich mit gängigen Programmiersprachen, modernen Frameworks und ausreichend Entwicklungserfahrung in verhältnismäßig kurzer Zeit implementieren. Und daraus folgt nicht selten – vor allem auf Managementebene – der Trugschluss, dass die Schnittstelle daher ziemlich schnell fertig sein müsste. Tatsächlich ist es dagegen aber äußerst empfehlenswert, sich deutlich mehr Zeit zu nehmen und zunächst einige konzeptionelle Gedanken darüber zu machen, wie genau die API gestaltet werden soll. Denn ist eine Schnittstelle erst einmal in Betrieb genommen, und wird sie von anderen Systemen verwendet, dann sind grundlegende Änderungen an der Schnittstelle oft nur noch schwierig umzusetzen. Die erste Version sollte daher gut durchdacht sein und bereits eine hohe Qualität aufweisen.
In diesem Vortrag gibt Thilo Frotscher anhand unterschiedlicher Beispiele wertvolle Tipps aus der Praxis des guten API-Designs:
API-Ansätze im Vergleich
Zunächst ist es wichtig sich klarzumachen, wo genau und zu welchem Zweck die HTTP-API eingesetzt werden soll. Es lassen sich mindestens die folgenden vier typischen Einsatzgebiete beobachten:
- Single Page Applications (SPA)
- Systemintegration innerhalb eines Unternehmens oder zwischen Geschäftspartnern
- Microservice-Architekturen
- Public APIs
Diese Einsatzgebiete unterscheiden sich zum Teil sehr deutlich, insbesondere in der Frage, wie viele Clients eine API typischerweise haben wird, ob diese zur Entwicklungszeit bekannt sind, und inwiefern API-Betreiber und API-Nutzer ihre Entwicklungszyklen aufeinander abstimmen können.
Bei Single Page Applications wird in der Regel im Backend eine HTTP-API bereitgestellt, die ausschließlich von einem einzigen Client verwendet wird, und zwar von einem JavaScript-Frontend, das im Browser läuft. Der API-Client ist also wohlbekannt und die Entwicklung von API und Client erfolgt in der Regel im gleichen Team oder Unternehmen, typischerweise zeitlich eng aufeinander abgestimmt.
Im Falle von Microservice-Architekturen oder der Integration von Softwaresystemen im Unternehmenskontext hat eine API typischerweise mehrere Clients. Diese sind zwar bekannt, werden aber in aller Regel von unterschiedlichen Teams entwickelt, mit denen etwaige Änderungen abzustimmen sind. In diesem Szenario wird es also schon deutlich wichtiger, eine einmal veröffentlichte API stabil und konsistent zu halten. Nicht rückwärtskompatible Änderungen sind möglichst zu vermeiden, mindestens aber mit allen Kommunikationspartnern abzustimmen.
Die größte Herausforderung stellen Public APIs dar, bei denen Unternehmen oder Behörden eine öffentlich verfügbare Schnittstelle anbieten, ohne zur Entwicklungszeit zu wissen, wer diese einmal verwenden wird. Stellt sich der erhoffte Erfolg ein, führt dies potentiell zu einer großen Anzahl an API-Clients, zu deren Entwicklungsteams normalerweise kein oder zumindest kein regelmäßiger Kontakt besteht. In einem solchen Fall sind daher die höchsten Qualitätsanforderungen an die API zu stellen.
Was ist gutes API-Design?
Gutes API-Design ist generell wichtig, damit die Schnittstelle leicht erweiterbar und zu warten ist. Auch Konsistenz und leichte Verständlichkeit sollten stets im Fokus stehen. Wenn eine API etwa die Möglichkeit bietet, über verschiedene Endpunkte nach Kunden, Produkten oder Bestellungen zu suchen, dann sollte die Suche in all diesen Fällen gleich funktionieren. Beispielsweise sollten Query Parameter, die an unterschiedlichen Stellen das gleiche bewirken, auch überall den gleichen Namen haben. Dies führt zu einer flachen Lernkurve und somit dazu, dass Client-Entwickler schnelle Erfolge erzielen.
Die Wichtigkeit eines guten API-Designs variiert allerdings mit dem Einsatzgebiet der Schnittstelle. Während bei Single Page Applications sicherlich Abstriche gemacht werden können, sollte am anderen Ende der Skala im Falle von Public APIs ein ganz besonderes Augenmerk auf das API-Design gelegt werden. Denn Sinn und Zweck von Public APIs ist es ja meistens, neue Kunden und Vertriebskanäle zu erschließen. Nicht wenige Unternehmen erzielen inzwischen höhere Umsätze über ihre APIs als über ihre eigentlich populären Web-Angebote. Für andere Unternehmen wiederum ist die API sogar die einzige Einnahmequelle ihres digitalen Geschäftsmodells. Wenn also die Monetarisierung von APIs angestrebt wird, dann ist diese API folglich ein Produkt, in dessen Produktdesign genauso zu investieren ist, wie es auch bei einem traditionellen Produkt der Fall wäre. Schlechtes Design gefährdet dagegen den Erfolg und wirft kein gutes Licht auf den Hersteller, also den API-Betreiber.
Grundlegende Ausgangsfragen
Wie beginnt man am besten? Zunächst sollte man sich die folgenden Fragen stellen:
- Welches ist der Zweck der API?
- Wie viele Clients wird sie haben? Kenne ich sie? Welche Anforderungen haben diese an die Schnittstelle?
- Welche Daten sollen über die Schnittstelle zugänglich sein (und welche nicht)? Wie sehen sinnvolle Repräsentationen dieser Daten aus?
- Welche Funktionalität soll angeboten werden, und wie lässt sich diese so einfach wie möglich nutzen?
Nicht alle diese Fragen sind leicht zu beantworten. Das gilt insbesondere dann, wenn man seine Clients im Voraus nicht kennt. Wichtig ist es aber auf jeden Fall, dass sämtliche Daten über die Schnittstelle so präsentiert werden, dass sie auch für Unternehmens- oder Branchenfremde leicht verständlich sind. Kryptische Abkürzungen und ungewöhnliche Datenformate sind zu vermeiden.
Bei sämtlichen Überlegungen sollte man stets im Auge behalten, wer letztlich die Kunden bzw. die Nutzer des Produktes sind. Im Falle von APIs sind dies: Software-Entwickler. Und zwar diejenigen Entwickler, die Clients für die API implementieren sollen. Wer APIs betreibt und anbietet, sollte sich daher immer in die Rolle dieser Client-Entwickler hinein versetzen und hinterfragen, welche Informationen, Hilfestellungen und API-Eigenschaften für sie hilfreich wären, um eine möglichst gute Developer Experience (DX) zu erzielen. Dies fördert den Einsatz und die Verbreitung der API.
Themen für Detailentscheidungen
Welches sind nun aber die typischen Fragestellungen beim API-Design? In der Regel sind vor allem die folgenden Entscheidungen zu treffen:
- Grundlegendes Muster für den Aufbau von URL-Pfaden der API-Endpunkte. Dies schließt sinnvolle Namen für die Ressourcen mit ein.
- Einsatz von Hypermedia: ja oder nein
- Verwendung von HTTP-Methoden, z.B. PUT oder PATCH für Updates?
- Verwendete HTTP Status Codes
- Einheitliches Konzept für wiederkehrende Anforderungen von Clients, wie
- Angabe von Such- oder Filterkriterien
- Angabe des Detailgrades von angeforderten Daten
- Angabe der maximal gewünschten Anzahl von Resultaten
- Angabe einer Sortierreihenfolge
- Pagination (seitenbasiertes Blättern durch Daten oder Resultate)
- Unterstützte Repräsentationen der Daten: JSON, XML, Fotos / Grafiken, etc.
- Sicherheitsaspekte: Authentifizierung, API Keys, etc.
Richtlinien für das API-Design
Glücklicherweise ist die Anzahl der Themen also überschaubar. Und grundsätzlich ist es nicht nur ausreichend, sondern sogar sehr empfehlenswert, diese Entscheidungen nur einmal zu treffen. Die daraus resultieren Regeln werden dann zu verpflichtenden Design Guidelines für sämtliche APIs des Teams oder des Unternehmens. So stellt sich auch projektübergreifend eine Einheitlichkeit ein, die für alle Beteiligten von Vorteil ist. Entwickler im eigenen Team oder Unternehmen können leichter zwischen einzelnen Projekten wechseln und neue APIs schneller entwickeln, wenn einheitliche Richtlinien für das API-Design vorliegen. Für Kunden und andere Außenstehende macht eine solche Konsistenz über alle Schnittstellen sofort einen guten Eindruck.
Die Anfertigung eines API-Designs oder von Design Guidelines muss keinen großen Zeitaufwand bedeuten und lässt sich relativ schnell bewerkstelligen. Idealerweise sollte ein Experte hinzugezogen werden, der die notwendige Erfahrung mitbringt, um Vor- und Nachteile unterschiedlicher Alternativen zu verdeutlichen und entsprechende Empfehlungen zu geben.
Nicht zuletzt muss auch nicht jedes API-Design von Grund auf neu erstellt, das Rad nicht immer wieder neu erfunden werden. So sind die API-Design-Guidelines bekannter Unternehmen wie adidas, Zalando oder Google öffentlich zugänglich und dienen als Anschauungsmaterial. Hier finden sich viele clevere Lösungen, die gegebenenfalls übernommen werden können.
Das API Stylebook enthält Design Guidelines für die APIs von hochkarätigen Firmen wie Google, Deliveroo, PayPal sowie dem Weißen Haus.
Zudem existieren diverse Vorschläge für API-Design und Datenformate, wie JSON:API oder JSON-HAL. Mit OData liegt sogar ein offizieller Standard vor, der zwar im SAP- und Microsoft-Umfeld (auch aufgrund entsprechender Tool-Unterstützung) eine gewisse Verbreitung gefunden hat, abseits dieser Bereiche aber nur sehr wenige Anhänger gefunden hat.
Eine Einführung in das Design von HTTP-APIs – Zusammenfassung
Gutes Design ist essentiell für den Erfolg und die Wartbarkeit einer API. Je nachdem, wo eine API konkret eingesetzt wird, können gegebenenfalls Abstriche gemacht werden. Als Faustregel kann aber gelten: Je mehr Clients eine API haben wird, desto wichtiger ist das Design. Neben den genannten Fragestellungen sind eine gute und aktuelle Dokumentation, Stabilität und Konsistenz, Sicherheit und eine flache Lernkurve entscheidende Faktoren.
Für viele Aspekte des API-Designs haben sich Best Practices herauskristallisiert. Die Design Guidelines zahlreicher Unternehmen sind öffentlich verfügbar und dienen als Anschauungsmaterial. Zudem gibt es diverse Standards oder Formatvorschläge für API-Design. Trotz alledem ist es empfehlenswert, gegebenenfalls einen erfahrenen Experten zu Rate zu ziehen.
Ein API-Design sollte in der Regel nicht nur für eine einzige Schnittstelle gelten. Idealerweise werden daraus eigene Design Guidelines für das Team oder Unternehmen abgeleitet, die dann für sämtliche API-Projekte gelten sollten.
- Eine Einführung in das Design von HTTP-APIs - 13. Januar 2022
- Nützliche Public APIs im Überblick - 2. September 2020
