API-Lebenszyklus - Versionierung
Rubrik erklärt worauf es bei der Aktualisierung von APIs ankommt
Versionierung als Teil des API-Lebenszyklus
API-Änderungen sind unvermeidlich, wenn die Oberfläche einer Plattform wächst. Die Auswirkungen dieser Änderungen zu managen, kann eine Herausforderung sein, aber auf die Änderungen zu verzichten, führt zu einer schlechten Entwicklererfahrung aufgrund von falsch behandelten Fehlern. Die Versionierung verhindert nicht, dass ein Fehler auftritt, aber sie hilft zu kontrollieren, wo, wann und wie der Fehler auftritt. Dennoch müssen Entwickler ihren Code immer noch aktualisieren. Entwickler sollten diese Fragen bei der Einführung einer neuen API-Version berücksichtigen: Was sind die Gründe für die Erstellung einer neuen Version? Wie planen sie, die Änderungen an die Benutzer zu kommunizieren? Ist die neue Version eine bessere Version?
Rebecca Fitzhugh, Director of Developer Relations bei Rubrik , erläutert die Bedeutung der Versionierung beim API-Lebenszyklus:
„Um den Aufwand für ihre API-Kunden zu minimieren, sollten Unternehmen die API wie ein Produkt behandeln – auch wenn sie dem Kunden die Nutzung nicht in Rechnung stellen. Zu betrachten ist der gesamte API-Lebenszyklus; das bedeutet, dass eine klare Progression in eine semantisch versionierte API mit einem definierten Verfallszeitraum und -prozess zu haben. Dies wird dazu führen, dass sowohl die Entwicklungsteams als auch die API-Kunden weniger Probleme aufgrund von nicht kommunizierten Unterbrechungen haben werden.
Gründe für die Versionierung
Die Nutzung von API-Versionen kann helfen, die Komplexität zu reduzieren und schnell zu iterieren, wenn notwendige Änderungen identifiziert werden. Jedes Mal, wenn eine bahnbrechende Änderung stattfindet, sollte dies zu einer Änderung der API-Version führen. Dies gilt auch für das Entfernen eines Teils der API, das Ändern des Antworttyps und/oder das Ändern des Antwortdatenformats. Größere Versionsänderungen sind bei Non-Breaking-Änderungen, wie dem Hinzufügen neuer Endpunkte oder Antwortparameter, wahrscheinlich unnötig.
Mit einer guten Versionierungsstrategie ist es möglich, dass verschiedene Versionen der API nebeneinander existieren. Dies gibt dem API-Anbieter die Möglichkeit, die nächste API-Version zu erstellen und freizugeben, bevor die vorherige Version vollständig veraltet ist. Außerdem hat der Kunde so Zeit, seine bestehende Architektur zu überarbeiten, um die neue API-Version zu unterstützen.
Kommunikation ist der Schlüssel
Ungeplante API-Änderungen werden Kunden verärgern oder, schlimmer noch, könnten sich negativ auf das Geschäft auswirken. Wenn Unternehmen planen, eine neue API-Version zu veröffentlichen, sollten sie dies den Kunden so schnell wie möglich mitteilen.
Sie sollten in einer Nachricht die neue Version ankündigen, ein eventuell geplanter Lebenszyklus mit Details wie Zeitrahmen, Änderungsprotokoll, Support und Kontaktinformationen. Den Verfallszeitraum gilt es deutlich hervorzuheben, damit die Kunden innerhalb dieses Zeitrahmens mit der Aktualisierung des Codes beginnen können. APIs sind effektiv Verträge, sobald sie veröffentlicht sind. Anbieter haben ein Versprechen abgegeben, keine Brüche ohne ausreichende Benachrichtigung einzuführen.
Eine bessere Version
Die Versionierung ist ein wichtiger Teil der API-Strategie und des Designs. Sie gibt dem Entwicklungsteam im Laufe der Zeit die Möglichkeit, bessere Darstellungen für API-Ressourcen zu refaktorieren und zu veröffentlichen. Unternehmen sollten auf jeden Fall versuchen, ihre API vom ersten Tag an so perfekt wie möglich zu gestalten, aber bedenken, dass „Perfektion“ vergänglich ist, denn irgendwann werden Änderungen erforderlich sein. Mit einer „API als Produkt“-Denkweise wird die API einem vorhersehbaren Lebenszyklus mit einer Reihe von etablierten Praktiken für die Einführung neuer Endpunkte bis hin zur Veraltung folgen. API-Anbieter sollten sich gut überlegen, warum, wann und wie sie den Support für eine API-Version verwalten. Es empfiehlt sich, auf die Bedürfnisse der Kunden zu hören, die ihre Anwendungsfälle und Reibungspunkte bei der Nutzung der API mitteilen werden.
Der Erfolg einer API wird letztendlich am Erfolg der Verbraucher gemessen. Im 2019 State of API Report von Smartbear gaben über 50 Prozent der Verbraucher an, dass Geschwindigkeit oder Kosten der primäre Treiber für die Nutzung einer API sind. Das bedeutet, dass Unternehmen in die Kundenzufriedenheit investieren, indem sie ihre API benutzerfreundlicher gestalten.“
