Was sind die Vor- und Nachteile der API -Versionungsmethoden?

Question

Ich habe in einigen Beispielen zwei Möglichkeiten zur Versionierung einer API bemerkt.

Einer von ihnen verwendet eine Version in der URL

/api/v1/products

Der andere verwendet den Header des Inhaltstyps und den Header Akzeptieren, um die API -Version für die Daten zu markieren, die an den Server gesendet werden

Content-Type=application/vnd.company.v2+xml

Was sind die Vor- und Nachteile dieser Ansätze? Was sind ein Anwendungsfall, in dem Sie jeden Ansatz verwenden?

Answer 1

Ich habe es gewohnt, die Versionsnummer in der URL selbst (/v1/) zu haben. Ich persönlich denke, dass dies ein viel sauberer Ansatz ist. Auf diese Weise muss der Endbenutzer (oder der Entwickler) HTTP -Header nicht verarbeiten und kann einfach die REST -API/den Aufruf ändern, um nach Bedarf auf verschiedene Versionen der API zuzugreifen.

Ich denke, dass es auch möglich ist, dass einige der HTTP -APIs in verschiedenen Sprachen möglicherweise keine volle Unterstützung für HTTP -Header haben, sodass Sie immer die API für den Endbenutzer zur Verfügung stellen. Das Wiederumschreiben der URL ist der einfachste Weg, und es sollte mit allem funktionieren, was HTTP da draußen unterstützt.

Wenn die API -Version mithilfe der URL angegeben werden kann, ermöglicht es schließlich einfache Tests mit einem Webbrowser. Wenn Sie die Versionierung in einen HTTP -Header einbeziehen, muss der Entwickler eine Programmiersprache verwenden, um Tests zu testen.

Answer 2

Beide Mechanismen sind gültig. Sie müssen Ihren Verbraucher kennen, um zu wissen, welcher Weg Sie folgen müssen. Im Allgemeinen neigt die Zusammenarbeit mit Unternehmen und akademisch gesinnten Menschen dazu, Entwickler auf die Versionierung der Ressourcenheader zu verweisen. Wenn Ihre Kunden jedoch kleinere Unternehmen sind, wird der URL -Versionungsansatz weiter verwendet.

Hier sind die Vor- und Nachteile, die ich finden kann (ich bin sicher, es gibt mehr, und einige der Nachteile haben hier keine Arbeiten)

1. Es ist erforschender. Bei den meisten Anfragen können Sie einfach einen Browser verwenden, während die Implementierung der Ressourcenheader einen programmatischeren Ansatz für das Testen erfordert. Da jedoch nicht alle HTTP -Anfragen erforscht sind, beispielsweise Postanforderungen, sollten Sie ein REST -Client -Plugin verwenden, wie Postbote oder Pfote. URI Pro/Header Con

2. Mit einer uri-versionierten API, der Ressourcenidentifikation und der Repräsentation der Ressource wird miteinander übergeht. Dies verstößt gegen die Grundprinzipien der Ruhe; Eine Ressource sollte durch ein und nur ein Endpunkt identifiziert werden. In dieser Hinsicht ist die Auswahl der Ressourcenheader -Versioning akademisch idealistischer. Header Pro/Uri con.

3. Eine URI-versionierte API ist weniger fehleranfällig und vertrauter für die Kundenentwickler. Mit der Versionierung durch URL kann der Entwickler die Version eines Dienstes auf einen Blick herausfinden. F Der Client -Entwickler vergisst, eine Ressourcenversion in den Header aufzunehmen. Sie müssen entscheiden, ob sie in die neueste Version (was bei der Inkrementierung der Version zu Fehlern führen kann) oder einem 301 (dauerhaften bewegten Fehler) angewiesen werden soll. In beiden Fällen gibt es mehr Verwirrung für Ihre mehr Anfänger -Kundenentwickler. URI Pro/Header Con
4. URI -Versioning eignet sich dafür, dass sich mehrere Versionen in derselben Anwendung verprügeln. In diesem Fall müssen Sie Ihren Rahmen nicht weiterentwickeln. Hinweis: Wenn Sie dies tun, enthält Ihre Verzeichnisstruktur höchstwahrscheinlich eine beträchtliche Menge an doppelter Code im V2 -Verzeichnis. Das Bereitstellen von Updates erfordert auch einen Neustart des Systems - daher sollte diese Technik nach Möglichkeit vermieden werden. URI Pro/Header Con.
5. Es ist einfacher, die HTTP -Header für ein vorhandenes Projekt, das noch nicht von seiner Inception im Auge zu behalten war, Versioning hinzuzufügen. Header Pro/Uri con.
6. Laut dem RMM Level 3 REST -Prinzip: Hypermedia Controls, Sie sollten die Header vom Typ HTTP-Akzeptanz und Content-Typ verwenden, um die Versionierung von Daten zu verarbeiten und Daten zu beschreiben. Header Pro/Uri con.
7. Wenn Sie die Version in die URL einfügen, müssen Ihre Kunden eine Änderung ihres Codes (oder wenn sie intelligent sind, ihre Konfiguration) an die neue API koordinieren. Header Pro/Uri con.

Hier sind einige hilfreiche Links, wenn Sie weitere Lesen vornehmen möchten:

• Martin Fowlers Beschreibung des Richardson -Reifegradmodells
• API -Versioning - entscheidende Labors
• Hiteaos
• Der Artikel von Informit.com über Versioning -REST -Dienste

Answer 3

Besser zu verwenden Version in der URL. Ich suchte vor einiger Zeit danach und stieß auf die folgenden 2 Ressourcen, die diskutieren RESTFOR API -Design ausführlich.

1. Best Practices für die Gestaltung einer pragmatischen, erholsamen API - Version über die URL, nicht über Header.
2. Programmierer.Stackexchange.com : Was ist ein empfohlenes Muster für die Planung von REST -Endpunkten, die für vorausschauende Änderungen planen?

Tl; dresend: Die Verwendung von Version # in der URL ist ein empfohlener Ansatz.

Einige der am meisten verwandten APIs aller Zeiten, auf die ich gestoßen bin- Instagram -API und Stackoverflow.com API - Beide verwenden diesen Ansatz für die API-Versioning.