Bewährte Verfahren für die API-Versionierung?

Question

Gibt es bekannte Anleitungen oder bewährte Verfahren für die Versionierung von REST-APIs für Webdienste?

Ich habe festgestellt, dass AWS führt die Versionierung über die URL des Endpunkts durch . Ist dies der einzige Weg oder gibt es noch andere Möglichkeiten, das gleiche Ziel zu erreichen? Wenn es mehrere Möglichkeiten gibt, was sind die Vorzüge der einzelnen Möglichkeiten?

Answer 1

Es gibt einige Stellen, an denen Sie die Versionierung in einer REST-API durchführen können:

1. Wie bereits in der URI. Dies kann überschaubar und sogar ästhetisch ansprechend sein, wenn Weiterleitungen und dergleichen gut eingesetzt werden.

2. In der Kopfzeile "Akzeptiert:", so dass die Version im Dateityp enthalten ist. Wie 'mp3' gegenüber 'mp4'. Dies wird auch funktionieren, obwohl IMO es funktioniert ein bisschen weniger schön als...

3. In der Ressource selbst. Viele Dateiformate haben ihre Versionsnummern eingebettet, in der Regel in der Kopfzeile; dies ermöglicht es neuerer Software, "einfach zu arbeiten", indem sie alle vorhandenen Versionen des Dateityps versteht, während ältere Software aussteigen kann, wenn eine nicht unterstützte (neuere) Version angegeben wird. Im Zusammenhang mit einer REST-API bedeutet dies, dass sich Ihre URIs nie ändern müssen, sondern nur Ihre Antwort auf die jeweilige Version der Daten, die Sie erhalten haben.

Ich kann Gründe für alle drei Ansätze erkennen:

1. wenn Sie gerne neue APIs "säubern", oder bei größeren Versionsänderungen, bei denen Sie einen solchen Ansatz wünschen.
2. wenn Sie möchten, dass der Client vor der Ausführung eines PUT/POST weiß, ob es funktionieren wird oder nicht.
3. ob es in Ordnung ist, wenn der Client sein PUT/POST machen muss, um herauszufinden, ob es funktionieren wird.

Answer 2

Die Versionierung Ihrer REST-API erfolgt analog zur Versionierung jeder anderen API. Kleinere Änderungen können an Ort und Stelle vorgenommen werden, größere Änderungen erfordern möglicherweise eine völlig neue API. Am einfachsten ist es für Sie, jedes Mal von vorne anzufangen, weshalb es am sinnvollsten ist, die Version in die URL aufzunehmen. Wenn Sie dem Kunden das Leben leichter machen wollen, versuchen Sie, die Abwärtskompatibilität aufrechtzuerhalten, was Sie durch Veraltung (permanente Umleitung), Ressourcen in verschiedenen Versionen usw. erreichen können. Das ist etwas umständlicher und erfordert mehr Aufwand. Aber es ist auch das, was REST mit "Cool URIs don't change" fördert.

Letztendlich ist es wie bei jedem anderen API-Design auch. Wägen Sie den Aufwand gegen den Kundenkomfort ab. Erwägen Sie die Einführung einer semantischen Versionierung für Ihre API, die Ihren Kunden die Rückwärtskompatibilität Ihrer neuen Version deutlich macht.