Semantische Versionierung von REST apis?

Question

Ich habe eine Anzahl von Versionierungsschemas für REST API ausgewertet (Header, URL, ...). Der bisher zuverlässigste Ansatz scheint die URL-Option zu sein: Sie funktioniert mit Proxies und ist nicht auf obskure Schemas wie dates for versioning angewiesen.

Jetzt, wenn ich mich umschaue, scheint jeder, der den URL-basierten Ansatz verwendet, Versionen wie v1, v2 und so weiter zu verwenden. Niemand verwendet Nebenversionen oder sogar ein Schema wie semantic versioning.

Dies wirft einige Fragen auf:

• Wann erhöhen Sie die Versionsnummer eines REST-API (für sicher, Sie weiteres Updates zu ihm haben, als in fünf Jahren nur ein einziges Mal)?
• Wenn Sie nur einen Bugfix haben, erhöhen Sie wahrscheinlich nicht die Versionsnummer, aber wie unterscheiden Sie beide Versionen?
• Wenn Sie einen sehr feingranularen Ansatz verwenden, erhalten Sie viele Versionen, die Sie parallel hosten müssen. Wie gehst du damit um?

Mit anderen Worten: Wie ein Unternehmen wie GitHub hat, macht zum Beispiel nur v3 heute (2015), wenn sie sich um im Geschäft sind bereits jetzt 7 Jahre? Bedeutet das, dass sie ihre api nur zweimal geändert haben? Das kann ich kaum glauben.

Irgendwelche Hinweise?

Answer 1

Die Hauptversionsnummer ist alles, was Sie für einen Webdienst benötigen. Da Ihre Kunden sich nur für rückwärtskompatible Änderungen interessieren und diese (wenn Sie die semantische Versionierung korrekt durchführen) erst dann eingeführt werden, wenn eine neue Hauptversion veröffentlicht wird.

Alle anderen Änderungen (einschließlich neuer Funktionen, Bugfixes, Patches usw.) sollten für Ihre Kunden "sicher" sein. Diese neuen Funktionen haben nicht von Ihren Kunden verwendet werden, und Sie möchten wahrscheinlich nicht fortsetzen, dass die ungepatchte Version, die Fehler X oder Y mehr als nötig enthält. Die vollständige Versionsnummer in Ihren URLs (oder welche Methode auch immer Sie für die API-Versionierung verwenden) würde bedeuten, dass Ihre Kunden die URL Ihrer API jedes Mal aktualisieren müssen, wenn Sie ein Update/Bugfix für Ihre API erstellen Verwenden Sie weiterhin eine ungepatchte Version, bis sie dies tun.

Dies bedeutet nicht, dass Sie semantische Versionierung natürlich nicht intern verwenden können! Verwenden Sie einfach den ersten Teil (Hauptversion) als Versionsnummer für Ihre API. Es macht einfach keinen Sinn, die vollständige Versionsnummer in Ihr URL/Header/anderes Versionierungssystem aufzunehmen.

Um Ihre Frage zu beantworten: Sie aktualisieren Ihre API jedes Mal, wenn Sie eine neue Version erstellen, aber Sie geben nur eine neue API-Version frei, wenn Sie eine neue Hauptversion haben. Auf diese Weise müssen Sie nur ein paar verschiedene Versionen hosten (und Sie können natürlich alte Versionen im Laufe der Zeit ablehnen).