Was ist der beste Weg, um REST-URIs zu versionieren? Derzeit haben wir eine Version # in der URI selbst, dh.
http://example.com/users/v4/1234/
für Version 4 dieser Darstellung.
Gehört die Version zum queryString? dh.
http://example.com/users/1234?version=4
Oder wird die Versionierung am besten auf eine andere Weise durchgeführt?
rest
versioning
clean-urls
Mike Pone
quelle
quelle
Antworten:
Ich würde sagen, dass es am besten ist, es Teil des URI selbst zu machen (Option 1), da v4 eine andere Ressource als v3 identifiziert. Abfrageparameter wie in Ihrer zweiten Option können am besten verwendet werden, um zusätzliche (Abfrage-) Informationen zur Anforderung und nicht zur Ressource zu übergeben .
quelle
Versions-URLs nicht, weil ...
Angenommen, Ihre Ressource gibt eine Variante von application / vnd.yourcompany.user + xml zurück. Sie müssen lediglich Unterstützung für einen neuen Medientyp application / vnd.yourcompany.userV2 + xml erstellen und durch die Magie der Inhaltsverhandlung Ihre v1 und v2-Clients können friedlich nebeneinander existieren.
In einer RESTful-Schnittstelle ist die Definition der Medientypen, die zwischen dem Client und dem Server ausgetauscht werden, am nächsten an einem Vertrag.
Die URLs, die der Client für die Interaktion mit dem Server verwendet, sollten vom Server bereitgestellt werden, der in zuvor abgerufene Darstellungen eingebettet ist. Die einzige URL, die dem Client bekannt sein muss, ist die Stamm-URL der Schnittstelle. Das Hinzufügen von Versionsnummern zu URLs hat nur dann einen Wert, wenn Sie URLs auf dem Client erstellen, was mit einer RESTful-Schnittstelle nicht zu tun ist.
Wenn Sie Änderungen an Ihren Medientypen vornehmen müssen, die Ihre bestehenden Kunden beschädigen, erstellen Sie eine neue und lassen Sie Ihre URLs in Ruhe!
Und für diejenigen Leser, die derzeit sagen, dass dies keinen Sinn macht, wenn ich application / xml und application / json als Medientypen verwende. Wie sollen wir diese versionieren? Du bist nicht. Diese Medientypen sind für eine RESTful-Oberfläche so gut wie nutzlos, es sei denn, Sie analysieren sie mithilfe von Code-Download. An diesem Punkt ist die Versionierung ein strittiger Punkt.
quelle
Ah, ich setze meinen alten mürrischen Hut wieder auf.
Aus ReST-Sicht spielt es überhaupt keine Rolle. Keine Wurst.
Der Client erhält eine URI, der er folgen möchte, und behandelt sie als undurchsichtige Zeichenfolge. Geben Sie ein, was Sie wollen, der Client hat keine Kenntnis von einer Versionskennung.
Der Kunde weiß, dass er den Medientyp verarbeiten kann, und ich rate Ihnen, Darrels Rat zu befolgen. Ich persönlich bin auch der Meinung, dass die Notwendigkeit, das in einer erholsamen Architektur verwendete Format viermal zu ändern, große, massive Warnsignale mit sich bringen sollte, dass Sie etwas ernsthaft falsch machen, und die Notwendigkeit, Ihren Medientyp so zu gestalten, dass er widerstandsfähig ist, vollständig umgeht.
In beiden Fällen kann der Client ein Dokument nur in einem Format verarbeiten, das er verstehen kann, und den darin enthaltenen Links folgen. Es sollte über die Verknüpfungsbeziehungen (die Übergänge) Bescheid wissen. Was in der URI enthalten ist, ist also völlig irrelevant.
Ich persönlich würde für http: // localhost / 3f3405d5-5984-4683-bf26-aca186d21c04 stimmen
Eine vollkommen gültige Kennung, die verhindert, dass weitere Client-Entwickler oder Personen, die das System berühren, sich fragen, ob v4 am Anfang oder am Ende eines URI stehen soll (und ich schlage vor, dass Sie aus Server-Sicht keine 4 haben sollten Versionen, aber 4 Medientypen).
quelle
Sie sollten die Version NICHT in die URL einfügen, Sie sollten die Version in den Accept Header der Anfrage einfügen - siehe meinen Beitrag zu diesem Thread:
Best Practices für die API-Versionierung?
Wenn Sie anfangen, Versionen in die URL einzufügen, erhalten Sie dumme URLs wie diese: http://company.com/api/v3.0/customer/123/v2.0/orders/4321/
Und es gibt eine Reihe anderer Probleme, die sich ebenfalls einschleichen - siehe meinen Blog: http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html
quelle
Diese (weniger spezifischen) SO-Fragen zur REST-API-Versionierung können hilfreich sein:
quelle
Es gibt 4 verschiedene Ansätze zur Versionierung der API:
Hinzufügen einer Version zum URI-Pfad:
Sie können einen Controller wie folgt in Ihren Code implementieren:
Versionierung der Parameter anfordern:
Die Implementierung kann folgendermaßen aussehen:
Übergeben eines benutzerdefinierten Headers:
Mit Header:
oder:
Mögliche Implementierung:
Ändern von Hostnamen oder Verwenden von API-Gateways:
quelle
Wenn die REST-Services vor der Verwendung eine Authentifizierung erfordern, können Sie den API-Schlüssel / das API-Token problemlos einer API-Version zuordnen und das Routing intern durchführen. Um eine neue Version der API zu verwenden, ist möglicherweise ein neuer API-Schlüssel erforderlich, der mit dieser Version verknüpft ist.
Leider funktioniert diese Lösung nur für auth-basierte APIs. Versionen werden jedoch nicht in die URIs aufgenommen.
quelle
Ich wollte versionierte APIs erstellen und fand diesen Artikel sehr nützlich:
http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http
Es gibt einen kleinen Abschnitt zum Thema "Ich möchte, dass meine API versioniert wird". Ich fand es einfach und leicht zu verstehen. Der springende Punkt ist, das Feld Akzeptieren im Header zu verwenden, um Versionsinformationen zu übergeben.
quelle
Ich würde die Version als optionalen Wert am Ende des URI einfügen. Dies kann ein Suffix wie / V4 oder ein Abfrageparameter wie von Ihnen beschrieben sein. Sie können sogar / V4 zum Abfrageparameter umleiten, damit Sie beide Varianten unterstützen.
quelle
Wenn Sie URIs für die Versionierung verwenden, sollte sich die Versionsnummer im URI des API-Stamms befinden, damit jede Ressourcen-ID sie enthalten kann.
Technisch gesehen bricht eine REST-API nicht durch URL-Änderungen (das Ergebnis der einheitlichen Schnittstellenbeschränkung). Es wird nur unterbrochen, wenn sich die zugehörige Semantik (z. B. ein API-spezifisches RDF-Vokabular) nicht abwärtskompatibel ändert (selten). Derzeit verwenden viele Leute keine Links für die Navigation (HATEOAS-Einschränkung) und Vokabeln, um ihre REST-Antworten zu kommentieren (selbstbeschreibende Nachrichtenbeschränkung), weshalb ihre Clients brechen.
Benutzerdefinierte MIME-Typen und die Versionierung von MIME-Typen helfen nicht, da das Einfügen der zugehörigen Metadaten und der Struktur der Darstellung in eine kurze Zeichenfolge nicht funktioniert. Ofc. Die Metadaten und die Struktur ändern sich häufig, daher auch die Versionsnummer ...
Um Ihre Frage zu beantworten, können Sie Ihre Anfragen und Antworten am besten mit Vokabeln ( Hydra , verknüpfte Daten ) versehen und die Versionierung vergessen oder nur durch nicht abwärtskompatible Vokabularänderungen verwenden (z. B. wenn Sie ein Vokabular durch ein anderes ersetzen möchten).
quelle
Ich stimme dafür in MIME-Typ, aber nicht in URL. Aber der Grund ist nicht der gleiche wie bei anderen.
Ich denke, die URL sollte eindeutig sein (mit Ausnahme dieser Weiterleitungen), um die eindeutige Ressource zu finden. Also, wenn Sie
/v2.0
in URLs akzeptieren , warum ist es nicht/ver2.0
oder/v2/
oder/v2.0.0
? Oder sogar-alpha
und-beta
? (dann wird es total zum Konzept des Semvers )Daher ist die Version im MIME-Typ akzeptabler als die URL.
quelle