Eine gut designte API sollte den Erwartungen der Entwickler:innen an Qualität und Standards entsprechen: DX is the new UX! Lars Röwekamp und Arne Limburg erläutern Schritt für Schritt alle acht Phasen des API Design Lifecycle. Sichere dir jetzt dein API Design Lifecycle Poster. Digital als Download oder in Printversion. Alle Informationen findest du im letzten Abschnitt des Blogartikels.
APIs sind der Schlüssel zur Erschließung neuer digitaler Kanäle. Sie ermöglichen interne und externe Datenbereitstellung, erhöhen die Partnerbindung und generieren neue Geschäftsmodelle.
Für das Unternehmen liefern APIs Datenzugriff und Agilität. Der Kunde kann die digitalen Mehrwerte vermarkten, Partner profitieren von der Generierung von B2B Synergien und das Marketing erhält Unterstützung von mobilen Initiativen.
Ein passende Business Modell spielt bei der Planung der API Strategie eine wichtige Rolle.
Entwickler müssen für die Nutzung der API zahlen (Pay-per-use, Stufenmodell, Freemium).
Entwickler werden an den generierten Umsätzen beteiligt.
Entwickler zahlen nicht direkt für die Nutzung der API, generieren aber zusätzlichen Umsatz.
Die Nutzung der API ist frei, Mehrwerte sind erweiterte Funktionalität sowie zusätzliche Nutzer und Daten.
Eine API sollte der Erwartungshaltung – DX aka Developer Experience – des Entwicklers an Qualität und Standards entsprechen. Sie sollte einfach und intuitiv zu verstehen, zu nutzen und zu testen sein und dabei in sich konsistent.
Während beim Ansatz "Code First" zunächst damit begonnen wird, eine API zu implementieren, um dann (aus Sicht des API-Entwicklers) zu schauen, woraus die API bestehen muss, rückt bei der Design-First-Strategie der Konsument der API in den Mittelpunkt. In der Design-Phase wird zunächst aus seiner Sicht betrachtet, wie die API sinnvoll aufgebaut werden muss. Eng damit verbunden ist die Strategie "Documentation First". Dabei wird das Design noch vor der Coding-Phase strukturiert dokumentiert (z.B. über OpenAPI). Diese Dokumentation hat den Vorteil, dass sich daraus mehr oder weniger automatisch verschiedene nützliche Artefakte wie Mocks, Prototypen, Test-Suites, Visualisierungen, Client-SDKs, Server-side Stubs und Policies erzeugen lassen, noch bevor die eigentliche Implementierung beginnt.
Der OpenAPI Standard bietet eine optimale Grundlage für den API First Ansatz:
• Verbesserte Developer Experience
• Governance für API Design & Kollaboration
• Sicherstellung von Wiederverwendbarkeit
OpenAPI unterstützt weitreichendes Tooling zur Automatisierung und Generierung von Artefakten für alle Phasen des API Lifecycle. Übergreifende API Design Guides sollten von Anfang an beim Design berücksichtigt werden.
Die Integration der API bildet das Bindeglied zwischen den User-Facing Interfaces und den Backend Services.
Das Spektrum von API Gateways reicht von einfachem Request-/Response-Proxying über Integration, Orchestration und Transformation bis hin zum Zugriffs- und Security-Management.
Das API Gateway schirmt die Backend Services vor direkten Zugriffen ab. Das umfasst die Überprüfung berechtigter Zugriffsanforderungen (Authentication & Authorization, API-Key-Management), den Schutz vor unberechtigten Zugriffen (Verhindern von DDoS-Attacken, z.B. über Throtteling oder Rate Limiting), Überprüfung von Service-Level-Agreements, bis hin zu der Überprüfung und/oder Manipulierung des Payloads (Analyse von und Schutz vor Injection), Payload-Mapping (z.B. zur Unterstützung alter Versionen).
Darüber hinaus kann ein API-Gateway Routing-Aufgaben wie Pfad-Mapping und/oder Request-Response-Mapping übernehmen, z.B. zur Umsetzung von Staging- und Rollout-Konzepten (z.B. Blue-Green-Deployments, Canary Deployments, siehe auch nächste Phase).
Teile der Aufgaben können auch durch Alternativen, wie Service Meshes, Load Balancer oder Security Gateways (Web-Application-Firewalls) übernommen werden.
Das Ausrollen einer API geht weit über die rein technische Bereitstellung der zugehörigen Services hinaus. Es gilt auch, Themen wie Downtime, Rollback, Testing und Change Managment zu berücksichtigen.
Es gibt verschiedene Arten von Deployments:
Bei diesem Ansatz wird die gesamte Service-Landschaft in einem Schritt deployed. Schlägt ein Teildeployment fehl, scheitert das gesamte Deployment. Deshalb spricht man hier auch von einem Alles-oder-nichts-Ansatz.
Das Multi-Service-Deployment verhält sich ähnlich wie das Basic Deployment. Der Unterschied liegt hier darin, dass Service-Gruppen gefunden werden, die gemeinsam deployed werden müssen. Diese werden dann, wie beim Basic Deployment alle gemeinsam deployed. Davon unabhänige Service-Gruppen werden unabhängig deployed.
Beim Blue-Green Deployment werden zunächst alle neuen Service-Instanzen deployed. Dabei wird durch eine Konfiguration im Load-Balancer sichergestellt, dass diese noch nicht erreichbar sind (sondern noch die alten Instanzen). Erst wenn alle neuen Service-Instanzen deployed sind, erfolgt über den Load-Balancer ein vollständiger Switch auf diese Instanzen. Dannach sind die alten Instanzen nicht mehr erreichbar und können heruntergefahren werden. Für ein Blue-Green-Deployment benötigt für einen kurzen Zeitraum die doppelte Menge an Service-Instanzen und damit die doppelte Menge an Ressourcen.
Im Gegensatz zum Blue-Green-Deployment erfolgt hier ein Mischbetrieb zwischen alten und neuen Service-Instanzen. Zunächst wird die erste der alten Service-Instanzen heruntergefahren. Dann wird die erste der neuen Service-Instanzen deployed. Ist dieses Deployment erfolgt, sorgt der Load-Balancer dafür, dass Traffic entweder auf die noch hochgefahrenen alten Instanzen oder auf die neue Instanz geleitet wird. So wird mit jeder weiteren Service-Instanz verfahren, bis alle neuen Instanzen deployed sind. Der Vorteil gegenüber Blue-Green-Deployments liegt darin, dass der Ressourcenbedarf bei einem Deployment konstant ist.
Beim Canary Deployment werden alte und neue Service-Instanzen parallel betrieben. Dabei wird sichergestellt, dass bestimmte Benutzergruppen nur auf die neuen Instanzen geroutet werden und andere Gruppen nur auf die alten. Auf diese Weise können neue Versionen zunächst mit einer kleinen Benutzergruppe getestet werden und dann Schritt für Schritt inkrementel weiteren Benutzergruppen zugänglich gemacht werden.
Die Wahl einer passenden Deployment Strategie ist eine Abwägung aus Komplexität, Management des Ausfallrisikos, Anforderungen an die Downtime (Zero Downtime?), und an die Rollback-Fähigkeit. Darüber hinaus spielen Testbarkeit und Test-Strategien und Last, but not Least die Deployment- und Betriebskosten eine Rolle.
Basic und Multi-Service Deployments bieten sich bei Release-Fenstern mit dedizierter Downtime an. Rolling und Blue-Green Deployments sichern Zero-Downtime. Canary Deployments erlauben die schrittweise Einführung neuer Features an Teile der Nutzer.
Entwickler für die eigene API zu gewinnen, beginnt damit, diese in einem Portal zu veröffentlichen. Die Entwickler durchlaufen eine Lernkurve, welche aus mehreren Phasen besteht. Es gilt, jede dieser Phasen optimal zu unterstützen.
Die erste Phase besteht daraus, die API zunächst zu entdecken und zu erforschen. Hat ein (Client-)Entwickler erst einmal verstanden, wie eine API funktioniert, kann er in die zweite Phase eintreten, nämlich das Evaluieren der Features, die eine API bereitstellt. Um diese ersten beiden Phasen gut zu unterstützen, ist es sinnvoll, den Konsumenten die Möglichkeit zu geben, die API (z.B. auf einem Testsystem) auszuprobieren, um das Verhalten besser zu verstehen.
Wenn dem Entwickler klar ist, wie er die API nutzen möchte, tritt er in die dritte Phase ein, nämlich der Entwicklung des Clients. Hier kann der Entwickler durch ein Client-SDK oder Beispiel-Code untgerstützt werden. Ein weiterer Fokus eines Developer Portals sollte die Unterstützung des Entwicklers bei den nun folgenden Phasen sein. Diese sind das Lösen von auftretenden Problemen, der Austausch mit anderen Entwicklern (z.B. durch Blog-Einträge und Foren) und ggf. die Interaktion mit den API-Anbietern, z.B. um Maintenance oder Features einzufordern. Dies kann z.B. durch ein öffentliches Ticketing-System passieren.
Ein Developer Portal dient als zentraler Anlaufpunkt für Client-Entwickler. Neben einem Getting Started Guide sollten daher auch weitere Code-Beispiele und Hands-On Tutorials enthalten sein, so wie How-To Guides für spezielle Features oder Probleme (wie Long Polling, Caching oder Optimistic Locking).
Darüber hinaus sollte eine klassische API Referenz enthalten sein, die neben möglichen Responses und Fehlercodes auch den Status der API enthält. Idealer Weise kann der Nutzer die API hier auch direkt ausprobieren (interaktive Dokumentation).
Ein Diskussionsforum, ein Blog und ein FAQ runden das Developer Portal ab.
Ein gut konzipiertes Developer Portal ist informativ, schafft Vertrauen in die API und dient zum Austausch der Nutzer-Community.
Ein ausgereiftes API Management und Monitoring ist essentiell, um das Nutzerverhalten zu verstehen und aufkommende Probleme frühzeitig zu erkennen und ihnen proaktiv entgegen zu wirken.
Dabei ist eine kontinuierliche Überwachung der APIs der Schlüssel für zeitnahe Aktionen und Reaktionen auf Probleme.
Ein ausgereiftes API Management und Monitoring sollte dabei mindestens überprüfen, ob APIs verfügbar sind und antworten (Availability). Die Statistik der Verfügbarkeit über einen gewissen Zeitraum (z.B. 90 Tage) wird als Uptime bezeichet. Diese sollte kontinuierlich visualisiert werden. Weitere Indikatoren für den Zustand einer API neben der Uptime Performance sind die Response-Times (Wie lange braucht eine API, um zu antworten) und die Failure Rate (Überprüfung z.B. über HTTP-Status-Code).
Ein weiterer wichtiger Block des API Monitorings ist die kontinuierliche Überwachung security-relevanter Aspekte wie Security Violations, API Vulnerabilities, DDos Attacken und Fraud Detektion.
Der dritte große Block ist die Beobachtung aller Business Activities, also fachlicher Metriken wie z.B. „Aufträge pro Stunde“. In diesen Bereich gehört auch das fachliche Monitoring von Third-Party-APIs. Um hier sinnvolle Metriken zu erhalten, kann die Validierung vorhandener Daten sinnvoll sein (z.B. Filtern von Ausreißern), es kann nötig sein, die Daten vor der Auswertung mehrstufig zu verarbeiten und es sollte immer der Kontext mit einbezogen werden (z.B. Saisonalität von API-Zugriffen).
Auf Basis des beschriebenen Monitoring sollte immer mindestens ein Alerting etabliert werden. Idealerweise erfolgen gewisse Aktionen auf Basis des Monitorings sogar vollautomatisch (z.B. Sperren von API bei zu vielen fehlerhaften Zugriffen). Alerting und Action erfolgt dabei auf Basis einer kontextsensitiven Baseline (e.g. saisonale Peaks).
Für eine erfolgreiche API gilt es, die in Phase 1 getroffenen Annahmen über Business Objectives und Nutzerverhalten regelmäßig mit den realen Werten zu vergleichen und bei Bedarf an die Realität anzupassen.
Das Feedback aus den anderen Phasen des API Lifecycles sollte regelmäßig und proaktiv erfolgen.
Als Basis für eine API Evolution dienen u.a. folgende Eingaben aus den Phasen des API Lifecycle:
Es sollte regelmäßig überprüft werden, ob die ursprüngliche Zielsetzung und geplante Art der Nutzung noch mit der Realität übereinstimmen. Darauf basierend sollte auch das Business Modell ggf. angepasst werden.
Auch das ursprünglich gewählte API Design sollte nicht als starr betrachtet werden, sondern regelmäßig auf den aktuellen Stand der Technik gebracht werden. Dazu kann z.B. die Aufnahme von Eventing in die API Design Guidelines zählen oder andere Änderungen an den Guidelines, die auf gemachter Erfahrung basieren.
Bei Änderungen am API Design sollte immer berücksichtigt werden, ob es sich um interne oder öffentliche APIs handelt.
Bei der Weiterentwicklung bestehender und bei der Integration neuer APIs sollten auch immer die Policies überprüft und ggf. angepasst werden.
Es sollte sich auch immer die Frage gestellt werden, ob Integration Patterns, die in der Vergangenheit angewendet wurden in den Punkten Komplexität und Flexibilität noch zu den aktuellen Anforderungen passen.
Teil der Betrachtung der bestehenden APIs sollte auch immer eine Analyse der Areas of Interest sein. Diese können einen guten Indikator für die Richtung der Weiterentwicklung darstellen. Das Ergebnis sollte immer in einen Kontext gestellt werden und diskutiert und bewertet werden. Zum Beispiel ist es ein Unterschied, ob es zu einem bestimmten Teil der API viele Rückfragen gibt, weil er so häufig verwendet wird oder ob das daran liegt, dass er schlecht dokumentiert oder kompliziert in der Verwendung ist.
Neben Nutzungsstatistigken von Blog-Einträgen und Support-Anfaragen sollten auch immer die Ergebnisse des automatisierten Monitorings mit fachlichen und technischen Metriken Teil der Analyse sein. Die sinnvolle Wahl dieser Metriken spielt dabei eine große Rolle und sollte auch angepasst werden, wenn man merkt, dass eine Information fehlt.
Eine gut durchdachte Evolution-Strategie erlaubt es, technische und funktionale Änderungen an der API vorzunehmen, ohne dabei Clients durch nicht abwärtskompatible Breaking Changes zu verlieren.
Dabei sollte bei der Weiterentwicklung der API immer Rücksicht darauf genommen werden, um was für einen Konsumenten es sich handelt und in welcher Beziehung er zum Anbieter der API steht.
Für die Evolution einer API bedarf es einer passenden Versionierungsstrategie:
Wenn es genau einen Konsumenten der API gibt (z.B. das eigene Frontend), der auch noch vom selben Team entwickelt wird, ist es möglich, diesen immer gleichzeitig mit der API zu deployen. Dann muss die verwendete API weder abwärtskompatibel noch versioniert sein.
Wenn sich Konsument und Anbieter der API in der selben Organisation befinden, ist es möglich, über Consumer-Driven Contract Testing sicherzustellen, dass nach einer Änderung an der API noch alle Konsumenten weiterhin funktionieren. Änderungen müssen dann zwar dennoch abwärtskompatibel realisiert werden, über die Consumer-Contracts kann aber festgestellt werden, wenn alte Teile der API nicht mehr benutzt werden. Diese können dann abgeschaltet werden. Das Vorgehen entspricht dann API expand-contract.
Wenn es Clients gibt, deren Update sich über einen längeren Zeitraum ziehen kann (z.B. mobile Clients) ist es sinnvoll, die Technik „API Expand-Contract“ anzuwenden. Dabei wird die API zunächst nur abwärtskompatibel erweitert (Expand) und erst wenn alle Clients auf dem aktuellen Stand sind, werden alte, nicht mehr benutzte Teile entfernt (Contract).
Über den Einsatz von Consumer-Contracts kann festgestellt werden, wann alle Clients auf dem neuesten Stand sind.
Wenn man mit dem Konsumenten der API in einem Vertragsverhältnis steht (z.B. B2B-Client), sollte darin auch immer festgehalten sein, wie lange alte Versionen zur Verfügung stehen müssen. In solchen Situationen sollte nicht angestrebt werden, „für immer“ abwärtskompatibel zu sein. Stattdessen sollten regelmäßig neue Versionen released werden, die dann aber eine abwärtskompatible Weiterentwicklung der API darstellen. Auf diese Weise kann einerseits sichergesetllt werden, dass der Client bei kontinuierlichen Updates keinen großen Anpassungsaufwand hat, andererseits können alte Versionen aber auch abgekündigt und nach der vereinbarten Zeit abgeschaltet werden.
Wenn man bei einer öffentlichen API keine Konsumenten verlieren möchte, sollte es das Ziel sein, die API so weterzuentwickeln, dass auch die allererste Version ohne großen Aufwand „für immer“ unterstützt werden kann. Dies kann erreicht werden, in dem die API „in der Regel“ abwärtskompatibel weiterentwickelt wird, in dem nur optionale Attribute hinzugefügt werden. Nur in Ausnahmefällen sollte eine neue Version released wird, die dann aber nur dazu dienen sollte, veraltete Attribute zu entfernen.
Lars Röwekamp und Arne Limburg wünschen viel Freude mit dem Poster. Bei Rückenfragen stehen die beiden gerne zur Verfügung.
In einer Live Coding Session zeigt Arne, wie man eine REST-Schnittstelle auf einfache Art abwärtskompatibel weiterentwickeln kann. Die etwa 30-minütigen Aufzeichnungen der Talks und die wichtigsten Fragen und Sourcen haben wir in diesem Blogartikel zusammengefasst.
