Versionierung von REST-APIs. Jede API hat eine eigene Version

Es ist üblich, die Version der REST-APIs in der URL anzugeben, insbesondere am Anfang des Pfads, dh in etwa wie folgt:

POST /api/v1/accounts
GET /api/v1/accounts/details

Ich habe jedoch kein Design gesehen, bei dem die Version mit jeder API verknüpft ist. Mit anderen Worten, wir pflegen die Version jeder API separat. dh:

POST /api/accounts/v2
GET /api/accounts/details/v3

Mit diesem Ansatz erhöhen wir die API-Version der spezifischen API, wenn Änderungen erforderlich sind, und müssen nicht die Version der gesamten APIs erhöhen.

Was sind die Nachteile dieses Stils anstelle des üblichen Stils?

— Eng.Fouad
quelle

Antworten:

Was Sie als einzelne REST-APIs bezeichnen, wird möglicherweise als REST-API- Ressourcensatz oder -Ressourcensatz bezeichnet . Sie können es auch als Funktionalität der REST-API betrachten . Wie bei jeder Art von Software wird das gesamte Paket versioniert / aktualisiert, nicht einzelne Funktionen oder Ressourcen.

Ihre Frage ist in dem Kontext sinnvoll, in dem die Ressourcen des REST-API-Pakets modular sind und möglicherweise separat entwickelt und versioniert werden.

Meines Erachtens sind die wichtigsten Nachteile Ihrer vorgeschlagenen Namenskonvention für Ressourcen-Locator:

Für den API-Benutzer würde dies zu viel komplexeren Ressourcen-Locators führen, die weniger vorhersehbar, weniger einprägsam und weniger stabil sind.
Für die Modulentwickler ist es nun mehr Arbeit, sich mit dieser Versionierung in ihrem eigenen Ressourcen-Locator zu befassen .
Änderungen an den Ressourcen-Locators werden immer häufiger, da mehrere Module aktualisiert werden und die oben genannten Nachteile exponentiell sind.

Eines Ihrer Hauptziele beim Erstellen einer API ist die einfache Verwendung ...

Finden Sie vielleicht eine bessere Möglichkeit, eine wichtige Änderung einzuführen oder die REST-API sogar mit einem HTTP-Header zu versionieren?

Weitere Informationen zum Ansatz von HTTP-Headern finden Sie in den folgenden Antworten: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

— ClemC
quelle

Hier ist ein noch besserer Ansatz: Verwenden Sie die Inhaltsaushandlung, um Ihre API mit den Kopfzeilen Content-Typeund zu Acceptversionieren:

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

Um eine andere Version zu erhalten, fordern Sie sie einfach mit einem anderen Inhaltstyp an Accept. Auf diese Weise sind die von Ihrem Server unterstützten Versionen völlig unabhängig von Ihrer URL-Struktur. Der gleiche Server kann mehrere Versionen unterstützen, indem Sie einfach anhand des AcceptHeaders auswählen, mit welchem Server Sie antworten möchten. Wenn Sie bei verschiedenen Bereitstellungen für verschiedene Versionen bleiben möchten, können Sie alternativ einen Proxy vor verschiedene Versionen Ihres Dienstes stellen, der anhand des AcceptHeaders festlegt, an welchen Proxy Anforderungen weitergeleitet werden sollen .

Auf diese Weise können Sie auch neue Formate mit unterschiedlicher Semantik (nicht nur unterschiedlichen Versionen) auf denselben Endpunkten unterstützen. Zum Beispiel könnte das POSTEN einer Liste von Konten für /api/accountsdie Batch-Erstellung bedeuten, und Sie müssten keinen separaten API-Endpunkt dafür erstellen.

— Jack
quelle

omg der Accept-Header muss die schlechteste Wahl für die Versionssignalisierung sein. Verwenden Sie nach Möglichkeit einen Versionsheader und nach Bedarf einen URL-Pfad (z. B. AWS-Routing)

— Ewan,

@Ewan Warum? Ein benutzerdefinierter Versionsheader impliziert, dass verschiedene Versionen dieselbe Ressource sind, ohne Vermittler darüber zu informieren, dass der Inhalt möglicherweise unterschiedlich ist. Ein Caching-Proxy würde Ihren Header nicht verwenden, um zwischengespeicherte v1-Antworten auf v2-Anforderungen nicht zu liefern.

— Jack

Verwenden Sie den variablen Antwortheader, wenn Sie No-Cache für API-Anforderungen noch nicht verwenden. Inhaltstyp hat bereits eine Bedeutung, es für den privaten Gebrauch zu unterstellen, macht den Verbrauchern das Leben schwer

— Ewan

@Ewan Dafür gibt es den vndTeil und die +Syntax des Typs: um anzuzeigen, dass es sich um einen herstellerspezifischen Untertyp des application/jsonTyps handelt. Genau dafür sind Inhaltstypen konzipiert. Ihre Ressource ist in mehreren Formaten verfügbar. Sie fordern den Kunden auf, das gewünschte Format auszuwählen. Darüber hinaus gibt es keinen Grund, warum API-Anforderungen keine standardmäßige HTTP-Caching-Semantik verwenden können.

— Jack

Wenn Sie einen Fehler in myapi v2 beheben, geben Sie keinen neuen MIME-Typ zurück.

— Ewan

Wenn Sie jeden Endpunkt separat versionieren, müssen Sie in der Lage sein, jeden Endpunkt separat bereitzustellen.

APIs haben normalerweise eine Version, da sich alle Endpunkte in derselben Codebasis befinden und daher gemeinsame Abhängigkeiten aufweisen und zusammen bereitgestellt werden.

Wenn Sie die Version nicht aktualisieren, während Sie eine Änderung vornehmen, weil "Oh, ich bin mir ziemlich sicher, dass sich meine Änderung nicht darauf auswirkt", werden Sie Probleme bekommen, wenn Sie einen Fehler machen.

Darüber hinaus möchten Sie, dass sowohl Version 1 als auch Version 2 Ihrer API gleichzeitig bereitgestellt werden. Dies geschieht normalerweise, indem jede Version auf einem separaten Server bereitgestellt und der Datenverkehr entsprechend weitergeleitet wird.

Wenn Sie keine einzelne API-Version haben, wird dies viel komplexer.

— Ewan
quelle