wake-up-neo.com

Wie zur Version REST URIs

Was ist der beste Weg zu Version REST URIs? 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 in den queryString? dh.

http://example.com/users/1234?version=4

Oder wird die Versionierung am besten auf eine andere Weise durchgeführt?

103
Mike Pone

Ich würde sagen, dass es am besten ist, es als Teil der URI selbst (Option 1) zu definieren, 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 zu übergeben, die sich auf die request beziehen, anstatt auf die resource .

30
Zef Hemel

Versions-URLs nicht, weil ... 

  • sie brechen Permalinks
  • Die Änderungen der URL werden sich wie eine Krankheit über Ihre Benutzeroberfläche ausbreiten. Was machen Sie mit Repräsentationen, die sich nicht geändert haben, aber auf die Repräsentation verweisen, die sie hat? Wenn Sie die URL ändern, brechen Sie alte Clients. Wenn Sie die URL verlassen, funktionieren Ihre neuen Clients möglicherweise nicht.
  • Die Versionierung von Medientypen ist eine wesentlich flexiblere Lösung.

Wenn Sie davon ausgehen, dass Ihre Ressource eine Variante des Datentyps application/vnd.yourcompany.user + xml zurückgibt, müssen Sie lediglich die Unterstützung für einen neuen Medientyp application/vnd.yourcompany.userV2 + xml und durch die Magie der Inhaltsaushandlung Ihrer v1 und erstellen v2-Clients können friedlich nebeneinander existieren.

In einer RESTful-Schnittstelle liegt einem Vertrag am nächsten die Definition der Medientypen, die zwischen dem Client und dem Server ausgetauscht werden.

Die URLs, die der Client für die Interaktion mit dem Server verwendet, sollten vom Server bereitgestellt werden, der in zuvor abgerufenen Repräsentationen 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 einen Wert, wenn Sie auf dem Client URLs erstellen, was Sie nicht mit einer RESTful-Schnittstelle tun sollen.

Wenn Sie Ihre Medientypen ändern müssen, die Ihre bestehenden Kunden beschädigen, erstellen Sie einen neuen und lassen Sie Ihre URLs in Ruhe!

Und für die 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-Benutzeroberfläche ziemlich nutzlos, es sei denn, Sie analysieren sie mit Code-Download. Zu diesem Zeitpunkt ist die Versionsverwaltung ein strittiger Punkt.

191
Darrel Miller

Ah, ich ziehe meinen alten mürrischen Hut wieder an.

Aus der Sicht von ReST spielt es keine Rolle. Keine Wurst.

Der Client erhält eine URI, der er folgen möchte, und behandelt sie als undurchsichtige Zeichenfolge. Was auch immer Sie wollen, der Kunde hat no Kenntnis von einem Versionsbezeichner.

Der Kunde weiß, dass er den Medientyp verarbeiten kann, und ich empfehle, Darrels Rat zu befolgen. Ich persönlich bin der Meinung, dass die Änderung des Formats, das in einer erholsamen Architektur viermal verwendet wird, gewaltige Warnsignale mit sich bringen sollte, dass Sie schwerwiegende Fehler begehen, und die Notwendigkeit, Ihren Medientyp für die Widerstandsfähigkeit von Änderungen zu gestalten, völlig umgeht.

In jedem Fall kann der Client ein Dokument nur mit einem Format verarbeiten, das er verstehen kann, und Links darin folgen. Es sollte über die Linkbeziehungen (die Übergänge) Bescheid wissen. Was also in der URI ist, ist völlig irrelevant.

Ich persönlich würde für http: // localhost/3f3405d5-5984-4683-bf26-aca186d21c04 stimmen

Ein perfekt gültiger Bezeichner, der verhindert, dass weitere Client-Entwickler oder Personen, die das System berühren, fragen, ob v4 am Anfang oder am Ende einer URI eingefügt werden soll (und ich schlage vor, dass Sie aus Server-Sicht keine 4 haben sollten Versionen, aber 4 Medientypen).

21
SerialSeb

Sie sollten NICHT die Version in die URL einfügen. Sie sollten die Version in den Accept-Header der Anfrage einfügen - siehe meinen Beitrag in diesem Thread:

Best Practices für die API-Versionierung?

Wenn Sie anfangen, Versionen in die URL einzufügen, erhalten Sie dumme URLs wie folgt: http://company.com/api/v3.0/customer/123/v2.0/orders/4321/

Und es gibt eine Reihe anderer Probleme, die sich ebenfalls einschleichen - siehe mein Blog: http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html

11
jeremyh

Diese (weniger spezifischen) SO Fragen zu REST API-Versionierung können hilfreich sein:

5
Pete TerMaat

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 entscheidende Punkt ist, das Accept-Feld im Header zu verwenden, um die Versionsinformationen zu übergeben.

2
Asma Zubair

Wenn die REST - Dienste vor der Verwendung eine Authentifizierung erfordern, können Sie den API-Schlüssel/das Token leicht einer API-Version zuordnen und das Routing intern durchführen. Um eine neue Version der API zu verwenden, kann ein neuer API-Schlüssel erforderlich sein, der mit dieser Version verknüpft ist.

Leider funktioniert diese Lösung nur für auth-basierte APIs. Es hält jedoch Versionen von den URIs fern.

2
UberSteve

Wenn Sie für die Versionsverwaltung URIs verwenden, sollte sich die Versionsnummer im URI des API-Stamms befinden, sodass jeder Ressourcenbezeichner sie enthalten kann.

Technisch kann eine REST - API nicht bei URL-Änderungen aufbrechen (das Ergebnis der einheitlichen Schnittstellenbedingung). Es bricht nur dann ab, wenn die zugehörige Semantik (z. B. ein API-spezifisches RDF - Vokab) nicht abwärtskompatibel (selten) geändert wird. Derzeit verwenden viele ppl keine Links für die Navigation (HATEOAS-Einschränkung) und Vokabeln, um ihre REST -Antworten (selbstbeschreibende Nachrichteneinschränkung) zu kommentieren, weshalb ihre Kunden brechen.

Benutzerdefinierte MIME-Typen und die Versionierung des MIME-Typs helfen nicht, da das Zusammenfügen der zugehörigen Metadaten und der Struktur der Repräsentation in eine kurze Zeichenfolge nicht funktioniert. Ofc. Die Metadaten und die Struktur werden sich häufig ändern, also auch die Versionsnummer ... 

Um Ihre Frage zu beantworten, können Sie Ihre Anfragen und Antworten am besten mit Anmerkungen ( Hydra , Linked Data ) kommentieren und die Versionierung vergessen oder sie nur bei nicht abwärtskompatiblen Vokabeländerungen verwenden (wenn Sie möchten ersetze ein Vokab durch ein anderes).

1
inf3rno

Ich würde die Version als optionalen Wert am Ende der URI angeben. Dies kann ein Suffix wie/V4 oder ein Abfrageparameter sein, den Sie beschrieben haben. Sie können sogar/V4 zum Abfrageparameter umleiten, um beide Varianten zu unterstützen. 

1
Paul Morgan

Ich stimme dafür ab, dies in Mime-Art zu tun, aber nicht in URL . Aber der Grund ist nicht derselbe wie bei anderen Jungs.

Ich denke, dass die URL eindeutig sein sollte (mit Ausnahme der Weiterleitungen), um die eindeutige Ressource zu finden. Wenn Sie also /v2.0 in URLs akzeptieren, warum handelt es sich nicht um /ver2.0 oder /v2/ oder /v2.0.0? Oder sogar -alpha und -beta? (dann wird es total zum Konzept von semver )

Daher ist die Version in MIME-Typ akzeptabler als die URL.

0
Yarco

Es gibt vier verschiedene Ansätze zur Versionierung der API:

  • Version zum URI-Pfad hinzufügen:

    http://example.com/api/v1/foo
    
    http://example.com/api/v2/foo
    

    Wenn Sie Änderungen vorgenommen haben, müssen Sie die Version wie folgt erhöhen: v1, v2, v3 ... 

    Sie können einen Controller in Ihrem Code folgendermaßen implementieren:

    @RestController
    public class FooVersioningController {
    
    @GetMapping("v1/foo")
    public FooV1 fooV1() {
        return new FooV1("firstname lastname");
    }
    
    @GetMapping("v2/foo")
    public FooV2 fooV2() {
        return new FooV2(new Name("firstname", "lastname"));
    }
    
  • Versionierung der Parameter anfordern:

    http://example.com/api/v2/foo/param?version=1
    http://example.com/api/v2/foo/param?version=2
    

    Der Versionsparameter kann optional oder erforderlich sein, abhängig davon, wie die API verwendet werden soll.

    Die Implementierung kann wie folgt aussehen:

    @GetMapping(value = "/foo/param", params = "version=1")
    public FooV1 paramV1() {
        return new FooV1("firstname lastname");
    }
    
    @GetMapping(value = "/foo/param", params = "version=2")
    public FooV2 paramV2() {
        return new FooV2(new Name("firstname", "lastname"));
    }
    
  • Übergeben einer benutzerdefinierten Kopfzeile:

    http://localhost:8080/foo/produces
    

    Mit Kopfzeile:

    headers[Accept=application/vnd.company.app-v1+json]
    

    oder:

    headers[Accept=application/vnd.company.app-v2+json]
    

    Der größte Vorteil dieses Schemas liegt in der Regel in der Semantik: Sie stören den URI nicht mit der Versionierung.

    Mögliche Implementierung:

    @GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v1+json")
    public FooV1 producesV1() {
        return new FooV1("firstname lastname");
    }
    
    @GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v2+json")
    public FooV2 producesV2() {
        return new FooV2(new Name("firstname", "lastname"));
    }
    
  • Ändern von Hostnamen oder Verwenden von API-Gateways:  

    Im Wesentlichen verschieben Sie die API von einem Hostnamen in einen anderen. Sie können sogar einfach das Erstellen einer neuen API für dieselben Ressourcen aufrufen. 

    Sie können dies auch mithilfe von API-Gateways durchführen.

0
Javier C.