Strategien zum Aktualisieren oder Versionieren von Webdiensten?

Question

Ich möchte die Best Practices für die Behandlung verschiedener Versionen von Webdiensten lesen.

Um zu verdeutlichen, wenn Sie einige Web-Methoden als Web-Service zur Verfügung gestellt haben, möchten Sie ein Feature/Funktionalität hinzufügen und damit die Signatur dieser Methodenaufrufe ändern, wie geht das in einer Weise, die doesn brechen Sie nicht alle Ihre Kunden, die den Service gerade anrufen?

Stellen Sie den Dienst unter einer anderen URL bereit?

Sie Sie eine Version in dem Methodennamen setzen sich (MyMethod, MyMethodv2 usw. - igitt ..)

übergeben Sie in einer Version als Teil des Methodenaufruf zusammen mit einer Parameterliste?

Weiß jemand, wie Google oder Amazon dieses Szenario mit ihrer umfangreichen Web-Service-Bibliothek handhaben?

EDIT: Bis jetzt fand ich einige gute Informationen in diesem article from Oracle. Auch this blog entry zu einigen Java-Besonderheiten war nützlich. Ich bin immer noch neugierig, einige der anderen Ansätze zu sehen.

Answer 1

Die typische Art der Versionierung eines Webdienstes besteht darin, dass Clients die gewünschte Version angeben. Sie können einfache Einschränkungen wie "> 2.0", "< 1.5" oder "= 1.1" berücksichtigen. Natürlich möchten Sie die Anzahl der unterstützten Versionen für Ihre eigene Gesundheit minimieren. Wenn ein Client keine Version angibt, nehmen Sie die letzte an.

Techniken für die Bereitstellung der Version variieren. Einige befürworten die Verwendung der URL, andere ermutigen Kopfzeilen, einige könnten sie als Parameter des API-Aufrufs enthalten. Fast keiner würde jedoch den Namen der Methode ändern. Das entspricht der Versionierung "package" oder "namespace", von der der OSGi-Link spricht. Es wird das Upgrade sehr schwierig machen und die Leute davon abhalten, mehr zu aktualisieren als Änderungen am eigentlichen Dienst.

Es hängt auch davon ab, wie Sie auf Ihre Webservices zugreifen. Wenn Sie REST verwenden, ist es am sinnvollsten, die URLs sauber zu halten und Header zu verwenden (und es wäre trivial, sie bei Bedarf als Abfrageparameter zu verwenden). Wenn Sie SOAP/XMLRPC/whatever-RPC verwenden, ist es normalerweise in Ordnung, sie in die URL zu setzen.

bearbeiten 5/2011 FWIW, obwohl ich nicht einverstanden sind, Apigee's blog recommends putting the version in the URL.

Wie der Client die Version angibt, ist normalerweise ziemlich einfach. Was komplizierter ist, ist, wie Sie alle Versionen gleichzeitig ausführen. Die meisten Sprachen haben keine Möglichkeit, mehrere Versionen derselben Bibliothek/desselben Moduls/derselben Klasse/Funktion in dieselbe Laufzeitumgebung zu laden (sei es eine VM, ein Prozess oder was Sie haben). Der von Ihnen zur Verfügung gestellte OSGi-Link ist eine Java-Lösung, um dies zu ermöglichen.

In der Praxis wird OSGi für die meisten Situationen übertrieben sein. Es ist normalerweise einfacher, veraltete Anforderungen an einen anderen Server oder Prozess zu übertragen.

Der beste Weg, Ihre Dienste zu "versionieren", ist jedoch, Erweiterbarkeit und Flexibilität in ihnen zu bauen, so dass sie vorwärts und rückwärts kompatibel bleiben. Das bedeutet nicht, dass alle Versionen miteinander kompatibel sein müssen, aber aufeinander folgende Versionen sollten miteinander kompatibel sein.

Answer 2

Ich kann Ihnen sagen, dass die Lösung des Erstellens von doAPIFunction, doAPIFunctionV2 und doAPIFunctionV3 usw. nichts als Kopfschmerzen an dem Ort erzeugt hat, an dem ich arbeite. Hinzu kommt, dass der Mangel an eindeutig beschreibenden Funktionsnamen allerlei Wahnsinn bedeutet.

Sie möchten eindeutige API-Funktionsnamen, und wenn sich eine API ändert, besteht das Ziel darin, dies so rückwärtskompatibel wie möglich zu versuchen. Ich würde vorschlagen, Ihre Einstiegspunkte zu versionieren, damit jeder Einstiegspunkt eine stabile API unterstützt und doFunction in example.org/api-1.0/ sich von example.org/api-2.0 unterscheidet, wenn es einen guten Grund gibt, die Semantik zu ändern.

Answer 3

Ich bin mir nicht sicher, ob ich Ihre Frage richtig verstanden habe. Aber meine 2 Cent. Wenn sich die Signatur der Methode wie ein anderer neuer Parameter ändert, warum kann sie dann nicht optional gemacht werden? Wenn jedoch ein bestehender Parameterdatentyp geändert wird, ist er nicht anwendbar.

Wählen Sie dies aus, wenn es falsch ist. :)

Answer 4

Früher war es einfacher, wenn Sie den gleichen Webservice-Methodennamen und andere Parameter vor Jahren hätten. :)

Sobald Sie einen Webservice schreiben, machen Sie einen Vertrag mit den Kunden, dass dies das ist, was Sie unterstützen werden.

Für ältere Methoden würde ich vorschlagen, zu protokollieren, ob sie verwendet werden, und von wem, um zu sehen, ob Sie sie aktualisieren können.

Ansonsten sollten Sie nur eine neue Methode schreiben, damit Sie mehrere ähnliche Funktionsnamen haben, die sich durch eine Version unterscheiden.

Das Problem mit der Übergabe einer Versionsnummer ist, dass Sie sicherstellen müssen, dass die Clients immer eine gültige Nummer übergeben, die, wenn Sie die Stubs generieren, funktionieren, aber wenn Sie dies nicht tun, dann ist dies sehr zerbrechlich.

Das Einfügen einer Versionsnummer in den Namen scheint am besten für mich zu funktionieren, da es offensichtlich macht, was alt ist, und Sie können AOP verwenden, um ältere Versionen der Webservice-Methoden leichter zu protokollieren.

Answer 5

Eine Möglichkeit, dies abzuschwächen, besteht darin, nach Vertrag und Schnittstellen in Stein zu schreiben. Man kann nie wirklich Funktionssignaturen ändern, man kann sie jedoch überlasten. Betrachten Sie die .NET API. Einige Methoden sind veraltet, aber sie funktionieren weiterhin, da Programme, die um sie herum codiert sind, möglicherweise nicht mehr funktionieren. Eine neue Version des Service kann unter einem anderen URI (v2.webservice.com) verfügbar gemacht werden, um eine neue Roadmap zu erstellen, und v1 muss weiterhin unterstützt werden.