Fotolia
Best Practices bei der API-Versionsverwaltung mit Semantic Versioning
Mit Semantic Versioning (SemVer) erhalten Entwickler ein Versionsschema, das eine einfach umzusetzende Versionierung bei der Entwicklung erlaubt.
Entwickler verwenden in ihrer Karriere mindestens drei oder vier verschiedene Versionsschema bei der Softwareentwicklung. In nicht-technischen Bereichen ist es wichtig, einen Standard zu etablieren, um eine gewisse Konsistenz zu erzeugen. Leider trifft das nicht immer auf technische Bereiche zu. Die Anstrengungen bei der Suche nach einer Lösung können von Organisation zu Organisation unterschiedlich sein.
Das trifft umso mehr zu, wenn es um die API-Versionsverwaltung geht. Während ein Versionsschema für interne Projekte (oder vollständige Open-Source-Projekte) häufig ziemlich flexibel ist, muss ein API-Schema für alle Benutzer leicht verständlich sein.
Spezifikationen des Semantic Versioning
Wie der Name schon andeutet, ist die Semantic-Versioning-Spezifikation (SemVer) eine standardisierte Spezifikation zur Bestimmung, warum und wie die Versionsnummer einer Anwendung aktualisiert wird. SemVer ist einer der besten Standards, da er sich einfach nachverfolgen lässt und schnelle Entscheidungen bei der Entwicklung erlaubt.
Die SemVer-Spezifikation umfasst eine Liste von elf Regeln, die man bei der Anwendungsentwicklung befolgt. In diesem Beitrag werden nicht alle Regeln thematisiert, doch es wird die grundlegende Struktur der Versionsnummern erläutert: X.Y.Z (oder Major.Minor.Patch). Es wird jedoch empfohlen, dass sich Entwickler selbstständig mit alle elf Regeln genau beschäftigen.
Patch
Beginnen wir ganz unten. Die Patch (Z) –Version der API bestimmt die Anzahl der rückwärtskompatiblen Bugfixes, die in eine API unter der aktuellen Minor-Version (siehe unten) eingeführt wurden. Innerhalb der SemVer-Richtlinien wird ein Bug als interne Änderung definiert, die ein fehlerhaftes Verhalten behebt.
Minor
Die Minor (Y) –Version einer API identifiziert die Anzahl neuer und rückwärtskompatibler Funktionen, die in die API eingeführt wurden, oder ein Event, bei dem die Funktionen als veraltet gekennzeichnet (aber noch nicht entfernt) wurden. Diese Zahl wird erhöht, wenn innerhalb des Codes interne Verbesserungen oder Patch-Level-Änderungen vorgenommen wurden.
Major
Schließlich wird die Major (X) –Version der API nur erhöht, wenn rückwärts-inkompatible Änderungen zur API hinzugefügt werden. Im Fall, dass eine Änderung irgendeine vorher definierte Funktion der API stört (unabhängig wie stark sie diese stört) beziehungsweise diese nicht mehr funktioniert, muss die Major-Version erhöht werden.
Es ist wichtig zu beachten, dass, wann immer man Major- oder Minor-Versionen erhöht, die anderen Versionen auf Null zurückgesetzt werden. Damit wird sichergestellt, dass jede Version die Anzahl der darin enthaltenen Änderungen deutlich anzeigt.
Auch wenn das ziemlich unkompliziert ist, taucht bei Entwicklern immer wieder die Frage auf, wenn sie SemVer einsetzen: Mit welcher Version beginne ich?
Wenn man im Internet sucht, tauchen vier verschiedene Antworten auf (1.0.0, 0.1.0, 0.0.1 und 0.0.0). Laut den SemVer FAQs, sollte man mit Versionsnummer 0.1.0 beginnen. Diese bedeutet, dass ein Projekt noch nicht stabil ist (stabil bedeutet, dass die Major-Version mindestens 1 ist), es neue Funktionen, aber noch keine Bugfixes gibt.
Wie verwendet man SemVer nun in einer möglichst einfachen und komfortablen Weise, ohne dass die Nutzer mit unnötigen Informationen überladen werden? Die einfache Antwort ist, indem die volle X.Y.Z Versionsnummer in der API-Dokumentation referenziert und nur die Major-Version für die aktuelle API-Implementierung angezeigt wird.
Mehr zum Thema API:
REST APIs und SDN: Eine Einführung für Netzwerkspezialisten.
Offene APIs sind der Schlüssel für eine erfolgreiche Collaboration-Plattform.
Wie sich ein JSON-Framework per API mit Apple iOS integrieren lässt.
AWS-Programmierschnittstellen in Amazon API Gateway absichern.
Wie sich REST API-Endpunkte für Cloud-Anwendungen absichern lassen.
Das kann schwierig sein, da die API-Struktur seltsam ist. Sicher gibt es viele Best Practices, doch selbst große Anbieter haben unterschiedliche API-Designs. Als Resultat gibt es ein halbes Dutzend verschiedene Möglichkeiten, die aktuelle Version der API an die Benutzer zu übermitteln.
Eine häufig eingesetzte Option ist es, die API-Version zu übermitteln, indem die Major-Version im URL-Pfad erscheint (zum Beispiel http://ihre.api.com/v1/endpoint). Allerdings gibt es auch Gründe, sich gegen diesen Ansatz zu entscheiden. Einer der augenfälligsten Gründe ist, dass die Änderung der Major-Version die gesamte Endpunkt-URL verändert. Dennoch ist es eine gute Möglichkeit, um nicht mehr unterstützte, rückwärts-inkompatible API-Versionen zu behandeln.
Der Vorteil, wenn man nur die Major-Version innerhalb der API selbst anzeigt, ist, dass die Nutzer damit einen Indikator erhalten, der ihnen zeigt, dass ihre Implementierung solange funktioniert, wie ihre API-Version verfügbar ist. Als Entwickler ist es unglaublich frustrierend, eine API zu verwenden, die eine rückwärts-inkompatible Änderung freigibt, ohne dass die Major-Versionsnummer aktualisiert wurde.
Man muss außerdem erwähnen, dass SemVer nicht nur Zweifel über die Version beseitigen kann, sondern auch die Diskussion darüber, ob es an der Zeit sein könnte, die API-Version zu erhöhen. Solange keine rückwärts-inkompatible Funktionalität eingeführt wird, ist es definitiv nicht notwendig, die Major-Versionsnummer zu erhöhen.
Die Semantic-Versioning-Spezifikation ist nicht nur ein großartiges Tool, um die Effizienz zu verbessern und Unklarheiten über die Softwareversion zu beseitigen. Es ist außerdem eine gute Möglichkeit, der Anwendung und den Nutzern den Respekt zu verleihen, den sie verdienen. Eine vorhersehbare und gut dokumentierte Versionsspezifikation stellt sicher, dass die API den Erwartungen entspricht und beruhigt die Nutzer, dass die API-Funktionalität nicht ohne eine entsprechende Benachrichtigung erfolgt.
Folgen Sie SearchEnterpriseSoftware.de auch auf Twitter, Google+, Xing und Facebook!
