Entwerfen von Web APIs

Kapitel 4. Bewährte Methoden für die Gestaltung

Diese Arbeit wurde mithilfe von KI übersetzt. Wir freuen uns über dein Feedback und deine Kommentare: [e-mail]

In den vorangegangenen Kapiteln haben wir einen Überblick über verschiedene Ansätze für die Übertragung von Daten über deine Web-API gegeben. Jetzt, wo du mit der Transportlandschaft vertraut bist und weißt, wie du zwischen verschiedenen Mustern und Frameworks wählen kannst, wollen wir dir einige bewährte Methoden an die Hand geben, damit deine Entwickler das Beste aus deiner API herausholen können.

Entwerfen für reale Anwendungsfälle

Bei der Entwicklung einer API ist es am besten, Entscheidungen zu treffen, die auf konkreten, realen Anwendungsfällen beruhen. Gehen wir etwas näher auf diese Idee ein. Denke an die Entwickler, die deine API nutzen. Welche Aufgaben sollen sie mit deiner API erledigen können? Welche Arten von Apps sollten die Entwickler erstellen können? Für manche Unternehmen ist das so einfach zu beantworten wie "Entwickler sollten in der Lage sein, die Kreditkarten ihrer Kunden zu belasten". Für andere Unternehmen kann die Antwort offener ausfallen: "Entwickler sollten in der Lage sein, eine ganze Reihe von interaktiven Anwendungen in Verbraucherqualität zu erstellen.

Nachdem du deine Anwendungsfälle definiert hast, musst du sicherstellen, dass die Entwickler die Dinge, die sie tun sollen, auch tatsächlich mit deiner API tun können.

Häufig werden APIs auf der Grundlage der internen Architektur der Anwendung entwickelt und Details der Implementierung vernachlässigt. Das führt zu Verwirrung bei Drittentwicklern und zu einer schlechten Erfahrung für Entwickler. Deshalb ist es so wichtig, sich nicht auf die interne Infrastruktur deines Unternehmens zu konzentrieren, sondern auf die Erfahrung, die ein externer Entwickler bei der Interaktion mit deiner API machen sollte. Ein konkretes Beispiel dafür, wie du die wichtigsten Anwendungsfälle definierst, findest du im Abschnitt "Skizziere die wichtigsten Anwendungsfälle" in Kapitel 5.

Wenn du mit einem Entwurf anfängst, ist es leicht, sich viele "Was-wäre-wenn-Fragen" vorzustellen, bevor du ihn umsetzt und testest. Obwohl diese Fragen in der Brainstorming-Phase nützlich sind, können sie einen Entwurf in die Irre führen, weil sie dich dazu verleiten, zu viele Probleme auf einmal zu lösen. Wenn du einen bestimmten Arbeitsablauf oder Anwendungsfall auswählst, kannst du dich auf einen Entwurf konzentrieren und dann testen, ob er für deine Nutzer/innen funktioniert.

Expertenrat

Als wir Ido Green, Developer Advocate bei Google, fragten, was eine gute API ausmacht, war seine wichtigste Antwort: Fokus:

"Die API sollte es Entwicklern ermöglichen, eine Sache wirklich gut zu machen. Das ist nicht so einfach, wie es sich anhört, und du solltest dir darüber im Klaren sein, was die API nicht so gut kann."

Hinweis

Wenn du Hilfe brauchst, um die Zielgruppe der Entwickler/innen einzugrenzen, lies Kapitel 8.

Design für ein großartiges Entwicklererlebnis

Genauso wie wir Zeit damit verbringen, über das Nutzererlebnis in einer Benutzeroberfläche nachzudenken, ist es wichtig, über das Entwicklererlebnis in einer API nachzudenken. Für Entwickler ist die Hemmschwelle, APIs zu verlassen, sehr niedrig, so dass schlechte Erfahrungen zu Abwanderung führen. Umgekehrt ist die Benutzerfreundlichkeit das absolute Minimum, damit ein Entwickler deine API weiter nutzt. Gute Erfahrungen werden von den Entwicklern geliebt: Sie werden zu den kreativsten Innovatoren, die deine API nutzen, und zu Evangelisten für deine API.

Mach den Einstieg schnell und einfach

Für Entwickler ist es wichtig, dass sie deine API verstehen und schnell einsatzbereit sind. Die Entwickler nutzen deine API vielleicht, um zu vermeiden, dass sie eine zweite Produktreihe zur Unterstützung ihres Hauptprodukts entwickeln müssen. Lass sie diese Entscheidung nicht bereuen, wenn die API undurchsichtig und schwer zu benutzen ist.

Expertenrat

Egal, wie sorgfältig wir unsere Kern-API entwerfen und entwickeln, die Entwickler erstellen immer wieder Produkte, die wir nie erwartet hätten. Wir geben ihnen die Freiheit, das zu entwickeln, was sie wollen.

Die Entwicklung einer API ist ähnlich wie die Entwicklung eines Verkehrsnetzes. Anstatt einen Endzustand oder ein Ziel vorzuschreiben, erweitert eine gute API die Vorstellung dessen, was für Entwickler möglich ist.

Romain Huet, Leiter der Entwicklerbeziehungen bei Stripe

Die Dokumentation kann Entwicklern den Einstieg sehr erleichtern. Zusätzlich zu den Dokumenten, die die Spezifikationen einer API beschreiben, können Tutorials oder Anleitungen für den Einstieg hilfreich sein. Ein Tutorium ist eine interaktive Schnittstelle, die Entwicklern deine API näher bringt. Du kannst die Entwickler Fragen beantworten oder "Code" in einen Eingabebereich eingeben lassen. Ein Leitfaden ist ein eher kontextbezogenes Dokument als eine Spezifikation. Er bietet Informationen für Entwickler zu einem bestimmten Zeitpunkt - in der Regel bei den ersten Schritten, manchmal aber auch bei der Aktualisierung oder Umstellung von einer Version oder Funktion auf eine andere.

In einigen Fällen kannst du die Benutzerfreundlichkeit ergänzen, indem du interaktive Dokumentationen online bereitstellst, in denen Entwickler eine Sandbox haben, um deine API zu testen. Mehr über Sandkästen erfährst du in Kapitel 9. Oft können Entwickler diese Schnittstellen nutzen, um den Code zu testen und eine Vorschau auf die Ergebnisse zu erhalten, ohne eine Authentifizierung durchführen zu müssen. Abbildung 4-1 zeigt ein Beispiel von Stripes UI für diesen Zweck.

Abbildung 4-1. Entwickler können die Stripe-API ausprobieren, ohne sich anzumelden

Zusätzlich zur interaktiven Dokumentation können Tools wie Software Development Kits (SDKs) den Entwicklern bei der Nutzung deiner API sehr helfen. Diese Codepakete sollen Entwicklern helfen, ihre Projekte schnell zum Laufen zu bringen, indem sie einige der Transaktionsschichten und die Einrichtung einer Anwendung vereinfachen.

Im Idealfall sollten Entwickler deine APIs ausprobieren können, ohne sich anzumelden oder sich zu registrieren. Wenn sich das nicht vermeiden lässt, solltest du einen einfachen Anmelde- oder Anwendungserstellungsprozess anbieten, der die minimal erforderlichen Informationen erfasst. Wenn deine API durch OAuth geschützt ist, solltest du den Entwicklern die Möglichkeit geben, in der Benutzeroberfläche Zugriffstoken zu erstellen. Die Implementierung von OAuth ist für Entwickler/innen mühsam, und wenn es keine einfache Möglichkeit gibt, diese Token zu generieren, wirst du an diesem Punkt eine hohe Abbruchquote feststellen.

Auf Konsistenz hinarbeiten

Du möchtest, dass deine API intuitiv konsistent ist. Das sollte sich in den Namen deiner Endpunkte, den Eingabeparametern und den Ausgabeantworten widerspiegeln. Entwickler sollten in der Lage sein, Teile deiner API zu erraten, auch ohne die Dokumentation zu lesen. Wenn du nicht gerade eine größere Versionserweiterung oder ein größeres Release durchführst, ist es am besten, wenn du bei der Entwicklung neuer Aspekte einer bestehenden API auf Konsistenz achtest.

Du hast zum Beispiel eine Gruppe von Ressourcen bisher als "Benutzer" bezeichnet und deine API-Endpunkte entsprechend benannt, aber jetzt merkst du, dass es sinnvoller ist, sie "Mitglieder" zu nennen. Es kann sehr verlockend sein, auf die "Korrektheit" der neuen Welt hinzuarbeiten, anstatt sich auf die Konsistenz mit der alten zu konzentrieren. Aber wenn es sich um dieselben Objekte handelt, kann es für die Entwickler sehr verwirrend sein, wenn sie in URI-Komponenten, Anfrageparametern und an anderen Stellen mal als "Benutzer" und mal als "Mitglieder" bezeichnet werden. Bei den meisten inkrementellen Änderungen ist die Konsistenz mit den bestehenden Entwurfsmustern für deine Nutzer am besten.

Ein weiteres Beispiel: Wenn du an einigen Stellen ein Antwortfeld mit dem Namen user hast, dessen Typ manchmal eine Integer-ID und manchmal ein Objekt ist, muss jeder Entwickler, der diese beiden Antwort-Payloads erhält, prüfen, ob user eine Integer-ID oder ein Objekt ist. Diese Logik führt zu einer Aufblähung des Codes in den Codebasen der Entwickler, was suboptimal ist.

Das kann sich auch in deinem eigenen Code bemerkbar machen. Wenn du SDKs pflegst, wirst du immer mehr Logik hinzufügen müssen, um mit diesen Unstimmigkeiten umzugehen und eine nahtlose Schnittstelle für Entwickler zu schaffen. Du könntest dies auch auf der API-Ebene tun, indem du die Konsistenz aufrechterhältst, anstatt neue Namen für dieselben Dinge einzuführen.

Konsistenz bedeutet im Allgemeinen, dass es in deiner API eine Reihe von Mustern und Konventionen gibt, die sich so wiederholen, dass Entwickler die Verwendung deiner API vorhersagen können, ohne die Dokumentation zu sehen. Das kann alles sein, von Datenzugriffsmustern über Fehlerbehandlung bis hin zur Namensgebung. Konsistenz ist deshalb so wichtig, weil sie die kognitive Belastung der Entwickler verringert, die versuchen, deine API zu verstehen. Konsistenz hilft deinen bestehenden Entwicklern bei der Anpassung neuer Funktionen, indem sie die Zahl der Forks in ihrem Code reduziert, und sie hilft neuen Entwicklern, mit allem, was du auf deiner API aufgebaut hast, sofort loszulegen. Bei weniger Konsistenz hingegen müssen verschiedene Entwickler die gleiche Logik immer wieder neu implementieren.

Hinweis

Mehr zu diesem Thema erfährst du in Kapitel 5.

Fehlersuche leicht gemacht

Eine weitere bewährte Methode für die Entwicklung von APIs ist es, den Entwicklern die Fehlersuche zu erleichtern. Dies kann durch die Rückgabe von aussagekräftigen Fehlern oder durch die Entwicklung von Werkzeugen erreicht werden.

Bedeutsame Fehler

Was ist ein Fehler? Ein Fehler kann an vielen Stellen entlang deines Codepfads auftreten, von einem Autorisierungsfehler während einer API-Anfrage über einen Geschäftslogikfehler, wenn eine bestimmte Entität nicht existiert, bis hin zu einem Datenbankverbindungsfehler auf unterer Ebene. Bei der Entwicklung einer API ist es hilfreich, die Fehlerbehebung so einfach wie möglich zu gestalten, indem du Fehler systematisch organisierst und kategorisierst und festlegst, wie sie zurückgegeben werden. Falsche oder unklare Fehler sind frustrierend und können die Akzeptanz deiner APIs negativ beeinflussen. Die Entwickler können nicht weiterkommen und einfach aufgeben.

Aussagekräftige Fehler sind leicht zu verstehen, eindeutig und umsetzbar. Sie helfen den Entwicklern, das Problem zu verstehen und es zu beheben. Die Angabe von Details zu diesen Fehlern führt zu einer besseren Erfahrung für Entwickler. Fehlercodes, die maschinenlesbare Zeichenketten sind, ermöglichen es Entwicklern, Fehler in ihrer Codebasis programmatisch zu behandeln.

Zusätzlich zu diesen Strings ist es sinnvoll, Fehler in längerer Form hinzuzufügen, entweder in der Dokumentation oder an anderer Stelle in der Nutzlast. Diese werden manchmal auch als menschenlesbare Fehler bezeichnet. Noch besser ist es, diese Fehler für jeden Entwickler zu personalisieren. Wenn du zum Beispiel einen Testschlüssel im Live-Modus der Stripe-API verwendest, wird eine Fehlermeldung wie diese ausgegeben:

No such token tok_test_60neARX2. A similar object exists in 
test mode, but a live mode key was used to make this request.

Tabelle 4-1 zeigt Beispielfehler (sowohl empfohlene als auch nicht empfohlene) für bestimmte Situationen.

Tabelle 4-1. Beispielhafte Fehlercodes für verschiedene Situationen

Situation	Empfohlen	Nicht empfohlen
Authentifizierung fehlgeschlagen, weil das Token widerrufen wurde	token_revoked	invalid_auth
Der für den Namen übergebene Wert hat die maximale Länge überschritten	name_too_long	invalid_name
Die Kreditkarte ist abgelaufen	expired_card	invalid_card
Keine Erstattung möglich, weil eine Gebühr bereits erstattet wurde	charge_already_refunded	cannot_refund

Um dein Fehlersystem zu entwerfen, könntest du deine Backend-Architektur entlang des Codepfads einer API-Anfrage abbilden. Dabei geht es nicht darum, deine Backend-Architektur offenzulegen, sondern darum, die auftretenden Fehler zu kategorisieren und herauszufinden, welche Fehler den Entwicklern angezeigt werden sollen. Welche kritischen Aktionen werden von dem Moment an, in dem eine API-Anfrage gestellt wird, durchgeführt, um die Anfrage zu erfüllen? Erstelle eine Übersicht über die verschiedenen Fehlerkategorien, die im Verlauf einer API-Anfrage auftreten, vom Beginn der Anfrage bis zu den Servicegrenzen innerhalb deiner Architektur. Tabelle 4-2 enthält ein kurzes Beispiel, das dir den Einstieg erleichtern soll.

Tabelle 4-2. Fehler in übergeordnete Kategorien einteilen

Fehler-Kategorie	Beispiele
Fehler auf Systemebene	Problem mit der Datenbankverbindung Problem mit der Backend-Dienstverbindung Fataler Fehler
Fehler in der Geschäftslogik	Tarifgebundene Anfrage erfüllt, aber es wurden keine Ergebnisse gefunden Geschäftsbezogener Grund für die Verweigerung des Zugangs zu Informationen
Fehler bei der Formatierung der API-Anfrage	Erforderliche Anfrageparameter fehlen Kombinierte Anfrageparameter sind zusammen ungültig
Autorisierungsfehler	OAuth-Anmeldeinformationen sind für die Anfrage ungültig Der Token ist abgelaufen

Nachdem du deine Fehlerkategorien im gesamten Codepfad gruppiert hast, überlege, welche Kommunikationsebene für diese Fehler sinnvoll ist. Einige Optionen sind HTTP-Statuscodes und Header sowie maschinenlesbare "Codes" oder ausführlichere, für den Menschen lesbare Fehlermeldungen, die in der Nutzlast der Antwort enthalten sind. Denke daran, dass du eine Fehlerantwort in einem Format zurückgeben solltest, das mit deinen Nicht-Fehlerantworten übereinstimmt. Wenn du zum Beispiel bei einer erfolgreichen Anfrage eine JSON-Antwort zurückgibst, solltest du sicherstellen, dass der Fehler im gleichen Format zurückgegeben wird.

Vielleicht möchtest du auch einen Mechanismus, um Fehler von einer Dienstgrenze in ein einheitliches Format von deiner API-Ausgabe zu übertragen. Bei einem Dienst, von dem du abhängig bist, kann es zum Beispiel zu einer Reihe von Verbindungsfehlern kommen. Du würdest den Entwickler wissen lassen, dass etwas schief gelaufen ist und dass er es noch einmal versuchen sollte.

In den meisten Fällen willst du so spezifisch wie möglich sein, damit deine Entwickler die richtigen Maßnahmen ergreifen können. In anderen Fällen möchtest du vielleicht das ursprüngliche Problem verbergen, indem du etwas Allgemeineres zurückgibst. Dies kann aus Sicherheitsgründen geschehen. Zum Beispiel möchtest du wahrscheinlich nicht, dass deine Datenbankfehler nach außen dringen und zu viele Informationen über deine Datenbankverbindungen preisgeben.

Tabelle 4-3 enthält Beispiele dafür, wie du deine Fehler bei der Entwicklung deiner API organisieren kannst.

Tabelle 4-3. Gliedere deine Fehler in Statuscodes, Kopfzeilen, maschinenlesbare Codes und menschenlesbare Zeichenfolgen

Fehler-Kategorie	HTTP-Status	HTTP-Header	Fehlercode (maschinenlesbar)	Fehlermeldung (menschenlesbar)
Fehler auf Systemebene	500	--	--	--
Fehler in der Geschäftslogik	429	Retry-After	rate_limit_exceeded	"Du hast eine Ratenbeschränkung erhalten. Siehe Wiederholungsversuch nach und versuche es erneut."
Fehler bei der Formatierung der API-Anfrage	400	--	missing_required_parameter	"In deiner Anfrage fehlte ein {user} Parameter."
Auth-Fehler	401	--	invalid_request	"Deine ClientId ist ungültig."

Wenn du anfängst, deine Fehler zu organisieren, erkennst du vielleicht Muster, um die herum du eine automatische Benachrichtigung erstellen kannst. Du könntest z. B. das Schema für deine API so definieren, dass bestimmte Parameter erforderlich sind, und eine Bibliothek einrichten, die zu Beginn der Anfrage automatisch nach diesen Parametern sucht. Dieselbe Bibliothek könnte die ausführliche Fehlermeldung in der Nutzlast der Antwort formatieren.

Du solltest eine Möglichkeit schaffen, diese Fehler öffentlich im Internet zu dokumentieren. Du kannst dies in deine API-Beschreibungssprache (siehe Kapitel 7) oder deinen Dokumentationsmechanismus einbauen. Denke über die verschiedenen Fehlerebenen nach, bevor du die Dokumente schreibst, denn es kann kompliziert werden, mehrere Faktoren zu beschreiben, wenn es viele verschiedene Arten von Fehlern gibt. Du könntest auch in Erwägung ziehen, ausführliche Antwort-Payloads zu verwenden, um auf deine öffentliche Dokumentation zu verlinken. Hier kannst du den Entwicklern mehr Informationen über den Fehler geben, den sie erhalten haben, und darüber, wie sie ihn beheben können.

Für noch strukturiertere und detailliertere Empfehlungen zu aussagekräftigen Fehlern und Problemdetails für HTTP-APIs, siehe RFC 7807.

Werkzeuge bauen

Du solltest nicht nur den Entwicklern die Fehlersuche erleichtern, sondern auch dir selbst, indem du interne und externe Tools entwickelst.

Die Protokollierung von HTTP-Status, Fehlern und deren Häufigkeit sowie anderen Metadaten zu Anfragen ist sowohl für den internen als auch für den externen Gebrauch wertvoll, wenn es darum geht, Fehler bei Entwicklern zu beheben. Abbildung 4-2 zeigt das Dashboard von Stripe mit detaillierten Protokollen, die Entwicklern die Fehlersuche erleichtern. Es gibt viele fertige Protokollierungslösungen. Wenn du eine davon implementierst, solltest du vor der Fehlersuche im Echtzeitverkehr jedoch sicherstellen, dass du die Privatsphäre deiner Kunden respektierst, indem du alle personenbezogenen Daten (PII) unkenntlich machst. Mehr über Entwickler-Tools, die Entwicklern bei der Fehlersuche und -behebung helfen, findest du in Kapitel 9.

Abbildung 4-2. Das Stripe-API-Dashboard mit Anfrageprotokollen

Neben der Protokollierung ist es beim Aufbau einer API hilfreich, Dashboards zu erstellen, die Entwicklern helfen, aggregierte Metadaten zu API-Anfragen zu analysieren. Du könntest zum Beispiel eine Analyseplattform nutzen, um die am meisten genutzten API-Endpunkte zu ermitteln, ungenutzte API-Parameter zu identifizieren, häufige Fehler zu erkennen und Erfolgsmetriken zu definieren.

Wie bei der Protokollierung sind viele Analyseplattformen von der Stange erhältlich. Du kannst die Informationen in übergeordneten Dashboards darstellen, die eine visuelle, zeitbasierte Anzeige bieten. Du könntest zum Beispiel die Anzahl der Fehler pro Stunde in der letzten Woche anzeigen. Vielleicht möchtest du den Entwicklern auch vollständige Anforderungsprotokolle mit Details über die ursprüngliche Anforderung, ob sie erfolgreich war oder fehlgeschlagen ist, und die zurückgegebene Antwort zur Verfügung stellen.

Mach deine API erweiterbar

Ganz gleich, wie gut du deine API entwickelt hast, es wird immer einen Bedarf an Veränderungen und Wachstum geben, wenn sich dein Produkt weiterentwickelt und die Akzeptanz bei den Entwicklern steigt. Das bedeutet, dass du deine API erweiterbar machen musst, indem du eine Strategie für ihre Weiterentwicklung entwickelst. Dies ermöglicht es dir als API-Anbieter und deinem Entwickler-Ökosystem, innovativ zu sein. Außerdem kannst du so einen Mechanismus für den Umgang mit fehlerhaften Änderungen schaffen. Wir werden uns mit der Idee der Erweiterbarkeit befassen und untersuchen, wie man frühes Feedback, die Versionierung einer API und die Aufrechterhaltung der Abwärtskompatibilität einbeziehen kann. Weitere Details zur Skalierung von APIs durch die Entwicklung deines API-Designs findest du in Kapitel 6.

Expertenrat

APIs sollten Primitive bereitstellen, die neue Arbeitsabläufe ermöglichen und nicht einfach die Arbeitsabläufe deiner Anwendung widerspiegeln. Die Erstellung einer API dient als Tor für das, was die Nutzer der API tun können. Wenn du einen zu einfachen Zugang anbietest, kann das zu einer verwirrenden Integration führen und den Integratoren zu viel Arbeit aufbürden. Wenn du den Zugang zu hoch anlegst, kann es passieren, dass die meisten Integrationen einfach das widerspiegeln, was deine eigene Anwendung tut. Du musst das richtige Gleichgewicht finden, um Arbeitsabläufe zu ermöglichen, an die du bisher nicht gedacht hast, entweder als Teil deiner Anwendung oder innerhalb der API selbst, um Innovationen zu ermöglichen. Überlege dir, was deine eigenen Ingenieure in einer API brauchen würden, um die nächste interessante Funktion für deine Anwendung zu entwickeln, und mache dies dann zu einem Teil deiner öffentlichen API.

Kyle Daigle, Director of Ecosystem Engineering bei GitHub

Ein Aspekt der Erweiterbarkeit ist es, sicherzustellen, dass du eine Möglichkeit für Feedback mit deinen Top-Partnern geschaffen hast (mehr über Top-Partner findest du in Kapitel 10). Du brauchst eine Möglichkeit, bestimmte Funktionen oder Felder freizugeben und bestimmten privilegierten Entwicklern die Möglichkeit zu geben, diese Änderungen zu testen, ohne die Änderungen für die Öffentlichkeit freizugeben. Manche nennen das ein "Beta"- oder "Early Adopter"-Programm. Mehr über diese Programme erfährst du in Kapitel 10. Dieses Feedback ist äußerst wertvoll, um zu entscheiden, ob deine API so gestaltet wurde, dass sie ihre Ziele erreicht. Es gibt dir die Möglichkeit, Änderungen vorzunehmen, bevor die Akzeptanz groß ist und bevor wesentliche Änderungen einen hohen Kommunikations- oder Betriebsaufwand erfordern.

In manchen Fällen möchtest du vielleicht deine API versionieren. Es ist einfacher, ein Versionssystem zu entwickeln, wenn es schon in einem frühen Stadium in den Entwurf integriert wird. Je länger du mit der Implementierung der Versionskontrolle wartest, desto komplizierter wird die Umsetzung. Das liegt daran, dass es mit der Zeit immer schwieriger wird, die Abhängigkeitsmuster deiner Codebasis zu aktualisieren, damit alte Versionen abwärtskompatibel bleiben. Der Vorteil der Versionierung besteht darin, dass du mit neuen Versionen Änderungen vornehmen kannst, ohne die Abwärtskompatibilität der alten Versionen zu gefährden. Eine bahnbrechende Änderung ist eine Änderung, die dazu führt, dass eine bestehende Anwendung nicht mehr so funktioniert, wie sie es vor der Verwendung deiner APIs getan hat.

Hinweis

Weitere Informationen zur API-Versionierung findest du unter "Gliederungsschlüssel User Stories".

Storytime: Die Übersetzungsebene von Slack

2017 brachte Slack sein Produkt Enterprise Grid auf den Markt, bei dem es sich um ein föderiertes Modell seines vorherigen Angebots handelte. Infolge dieser Föderation musste Slack sein Nutzerdatenmodell grundlegend ändern, damit die Nutzer/innen mehreren "Arbeitsbereichen" angehören können.

In der API hatten die Nutzer bisher nur eine einzige ID. Im neuen föderalen Modell hatte jeder Benutzer eine (globale) Hauptbenutzer-ID für das Enterprise Grid und eine lokale Benutzer-ID für jeden Arbeitsbereich. Als die bestehenden Teams auf das Enterprise Grid-Produkt migriert wurden, sollten sich ihre Benutzer-IDs ändern. Dies hätte alle Anwendungen von Drittanbietern, die auf eine feste Benutzer-ID in der API angewiesen sind, beeinträchtigt.

Als das Slack-Entwicklungsteam dieses Problem erkannte, ging es zurück ans Reißbrett, um herauszufinden, was getan werden kann, um die Abwärtskompatibilität für Drittentwickler zu erhalten. Das Team beschloss, eine Übersetzungsschicht einzurichten. Diese zusätzliche Infrastruktur würde die Benutzer-IDs stillschweigend so übersetzen, dass sie mit denen übereinstimmen, die die Entwickler zuvor erhalten hatten.

Obwohl die Entscheidung, diese Übersetzungsschicht zu bauen, die Markteinführung des Enterprise Grid-Produkts um mehrere Monate verzögerte, war es für Slack von entscheidender Bedeutung, sicherzustellen, dass seine API abwärtskompatibel bleibt.

Für Unternehmen und Produkte, auf die sie sich verlassen, ist es schwierig, abwärtskompatible Versionen zu erhalten. Das gilt besonders für Anwendungen, die sich nicht so häufig ändern. Für viele Unternehmenssoftware gibt es niemanden, der sich um die Aktualisierung von Versionen kümmert, und es gibt keinen Anreiz für ein Unternehmen, in die Aktualisierung von Versionen zu investieren, nur weil du eine neue Version herausgebracht hast. Viele mit dem Internet verbundene Hardwareprodukte verwenden ebenfalls APIs, aber die Hardware verfügt nicht immer über einen Mechanismus zur Aktualisierung ihrer Software. Außerdem gibt es Hardware oft schon sehr lange - denk daran, wie lange du deinen letzten Fernseher oder Router besessen hast. Aus diesen Gründen ist es manchmal unerlässlich, dass du die Abwärtskompatibilität mit früheren API-Versionen aufrechterhältst.

Allerdings hat die Pflege von Versionen ihren Preis. Wenn du nicht die Kapazität hast, alte Versionen jahrelang zu unterstützen, oder wenn du nur wenige Änderungen an deiner API erwartest, solltest du die Versionen auf jeden Fall auslassen und eine additive Änderungsstrategie verfolgen, die auch die Abwärtskompatibilität in einer einzigen, stabilen Version aufrechterhält.

Wenn du in Zukunft mit größeren Änderungen und Aktualisierungen rechnest, empfehlen wir dir dringend, ein Versionsverwaltungssystem einzurichten. Selbst wenn es Jahre dauert, bis du die erste größere Versionsänderung vornimmst, hast du das System zumindest einsatzbereit. Der Aufwand, ein Versionsverwaltungssystem von Anfang an einzurichten, ist viel geringer, als es später einzuführen, wenn es dringend benötigt wird.

Hinweis

Mehr zur API-Versionierung findest du in Kapitel 7.

Storytime: Die Abschaffung einer API bei Twitch

Im Jahr 2018 beschloss die Online-Videostreaming-Plattform Twitch, eine veraltete API abzuschaffen und eine neue API bereitzustellen. Nachdem Twitch das Auslaufen der alten API angekündigt hatte, erhielt es viele Rückmeldungen von Entwicklern, die sagten, dass sie mehr Zeit bräuchten, um die Änderung zu bewältigen, da sonst ihre Integrationen nicht mehr funktionieren würden. Aufgrund dieser Rückmeldungen hat Twitch beschlossen, die Lebensdauer der alten API zu verlängern, um den Entwicklern ausreichend Zeit zu geben, ihren Code auf die neue API zu übertragen.

Schlussgedanken

Die Bedürfnisse deiner Nutzerinnen und Nutzer zu erfüllen, ist der Kern eines soliden API-Designs. In diesem Kapitel haben wir eine Reihe von bewährten Methoden vorgestellt, die dir dabei helfen, ein großartiges Entwicklererlebnis zu schaffen.

Während du deine API und dein Entwickler-Ökosystem aufbaust, entdeckst du vielleicht weitere bewährte Methoden, die auf dein Unternehmen, dein Produkt und deine Nutzer zugeschnitten sind.

In Kapitel 5 setzen wir diese Ideen in die Praxis um und führen dich durch die praktischen Schritte, um alles, was du in diesem Buch bisher gelernt hast, für die Entwicklung einer API zu nutzen.