Unterstützt mehrere API-Versionen in der Flasche

Begann ich das design eines RESTful-webservice mit Kolben und Python, und ich Frage mich, wie würde man die Unterstützung von mehreren API-Versionen im selben Projekt.
Ich bin am überlegen, setzen die angeforderte API-version in die URL wie folgt:

/myapp/v1/Users

Nach einiger Zeit möchte ich hinzufügen, dass ein weiterer Endpunkt in der Version 1.1 der API und halten alles aus v1, die nicht zu ändern:

/myapp/v1.1/Users   <= Same as in v1
/myapp/v1.1/Books

In v2 die "Benutzer"-Endpunkt geändert:

/myapp/v2/Users   <= Changed in v2
/myapp/v2/Books   <= Same as in v1.1

und so weiter...

Blick auf diese Frage, die einfachste Möglichkeit wäre wahrscheinlich so etwas wie dieses:

@app.route('/<version>/users')
def users(version):
    # do something
    return jsonify(response)

Aber ich kann mir vorstellen, dass dies schwieriger zu halten und mit jeder neuen API-version. Also ich Frage mich, ob es nicht besser (= leichter zu pflegen und besser strukturiert) Weise zu erreichen, das mit Fläschchen?

InformationsquelleAutor Keeper | 2015-03-01
  1. 68

    Ich bin der Autor von die akzeptierte Antwort auf die Frage, die Sie referenziert. Ich denke, die /<version>/users Ansatz ist nicht sehr effektiv ist, wie Sie sagen. Wenn Sie zu bewältigen haben drei oder vier verschiedene Versionen werden Sie am Ende mit spaghetti-code.

    Des nginx Idee habe ich vorgeschlagen, es ist besser, hat aber den Nachteil, dass Sie Gastgeber zwei separate Anwendungen. Ich habe damals verpasst, zu schweigen von einer Dritten alternative, die eine Blaupause für jede API-version. Betrachten Sie beispielsweise die folgenden app-Struktur (stark vereinfacht für die Klarheit):

    my_project
+-- api/
    +-- v1/
        +-- __init__.py
        +-- routes.py
    +-- v1_1/
        +-- __init__.py
        +-- routes.py
    +-- v2/
        +-- __init__.py
        +-- routes.py
    +-- __init__.py
    +-- common.py

    Hier haben Sie eine api/common.py implementiert, dass gemeinsame Funktionen, die alle API-Versionen benötigen. Zum Beispiel, können Sie eine Hilfsfunktion (nicht eingerichtet als route), die eine Antwort auf Ihre /users route, die identisch ist in v1 und v1.1.

    Den routes.py für jede API-version definieren der Routen, und wenn nötig, rufen Sie in common.py Funktionen zur Vermeidung einer doppelten Logik. Zum Beispiel, Ihr v1 und v1.1 routes.py haben kann:

    from api import common

@api.route('/users')
def get_users():
    return common.get_users()

    Hinweis: die api.route. Hier api ist eine Blaupause. Mit jeder API-version implementiert, die als Blaupause hilft vereinen alles, was mit der richtigen versionierten URLs. Hier ist eine Beispiel-app setup-code, der Importe der API-Blaupausen in der Anwendung Beispiel:

    from api.v1 import api as api_v1
from api.v1_1 import api as api_v1_1
from api.v2 import api as api_v2

app.register_blueprint(api_v1, url_prefix='/v1')
app.register_blueprint(api_v1_1, url_prefix='/v1.1')
app.register_blueprint(api_v2, url_prefix='/v2')

    Diese Struktur ist sehr schön, da es hält alle API-Versionen separate, aber Sie sind gedient durch die gleiche Anwendung. Als zusätzlichen Vorteil, wenn die Zeit kommt, um mehr unterstützen v1, die Sie gerade entfernen Sie die register_blueprint Anruf für diese version, löschen Sie die v1 Paket von Ihren Quellen und Sie sind fertig.

    Jetzt, mit dieser sagte, sollten Sie wirklich machen Sie eine Anstrengung, um Ihre design-API in einer Weise, die minimiert das Risiko, dass rev die version. Berücksichtigen Sie, dass das hinzufügen von neuen Routen nicht erforderlich, eine neue API-version, es ist völlig in Ordnung, zum erweitern einer API mit neuen Routen. Und änderungen in bestehenden Routen kann manchmal in einer Weise, die keine Auswirkungen auf alte Kunden. Manchmal ist es weniger schmerzhaft zu rev der API und haben mehr Freiheit, um die Dinge zu ändern, aber im Idealfall, dass nicht allzu oft vorkommt.

    • Das funktioniert Super, danke sehr!
    • Würden Sie mir die Bereitstellung der fehlenden Teile? Wo sind die Baupläne eigentlich erstellt? In welche Dateien? Und was macht die Blaupause Instanziierung Aussehen? Danke.
    • Hier ist ein Beispiel-API-Blaupause, aus meinem Buch: github.com/miguelgrinberg/flasky/tree/master/app/api_1_0
    • Danke. Ich paar Fragen wenn es dir nichts ausmacht. Habe ich das Recht verstanden? Sagen wir, ich habe eine erste version einer API (v1). Dann will ich v2. Ich kopiere den gesamten v1-Verzeichnis, und nennen Sie v2. Dann kann ich setup eine Blaupause in init.py von der v2-Verzeichnis und registrieren Sie es in der Haupt-app, wie beschrieben, in Ihrer ersten Antwort. Ich denke, meine Sorge ist, dass wir noch am Ende mit mehreren Versionen von dem code. Wenn eine Gruppe von Endpunkten ändert sich nicht von v1 nach v2, das code dupliziert werden an beiden Orten? Korrekturen angewendet werden müssen, um alle Versionen. Was ist der nutzen von Blaupausen? Struktur?
    • zuerst von allen, sollten Sie versuchen zu vermeiden mehrere Versionen, Wann immer möglich. Dies sollte eine Letzte Maßnahme, wenn Sie eine vollständige oder nahezu vollständige Neugestaltung der API. Für kleinere änderungen, design-Ihrer-API, so dass es sich entfalten kann. Aber wenn Sie benötigen, setzen einige Endpunkte, die auf mehr als eine API-version, es ist absolut kein problem in importieren, die aus einem gemeinsamen Modul oder Paket.
    • also, was ist Ihre Strategie für, wenn Sie haben ein voll entwickeltes API (v1) und willst dann add new "breaking" - Funktionen wie das ändern des formats der Antwort ausgeben. Und zur gleichen Zeit, die Sie wollen, um neue Endpunkte, die Sie nicht wollen, zur Verfügung, um aktuelle v1-clients? Mit einem gemeinsamen Modul funktioniert, bis eine version erfordert eine änderung, die brechen das andere. Tun Sie dann verschieben Sie eine Kopie der "geändert" - version in einem separaten vX-Verzeichnis?
    • Ich sehe ein paar Probleme mit Ihrem Szenario. Wenn Sie einen anderen Antwort-format nur verwenden verschiedene content-Typen (vielleicht vnd Typen), keine Notwendigkeit, um die Versionsnummer für, die. Endpunkte hinzufügen, dass Sie nicht wollen, v1 Kunden zu sehen, macht für mich keinen Sinn. Wenn Sie verhindern möchten, dass bestimmte clients immer eine Ressource, die nur einen Fehler zurück-code. Vielleicht 403 ist angemessen für diese?
    • Wie über dieses. Ich habe mehrere Versionen und bin mit der "Accept" - header zu ermöglichen, einen client, um anzugeben, die version, die Sie wollen. In der Flasche, wie kann ich das weiterleiten der Anfrage an geeignete version? Ich sehe ein paar Sachen über dispatchermiddleware, aber ich glaube nicht, siehe nichts über die Disposition basiert auf einer Variablen.
    • Kolben nicht bieten Versand basierend auf den Werten im request-Header, aber das ist etwas, das man leicht umsetzen kann mit einem Hilfs-Funktion oder Dekorateur.
    • Das ist das, was ich dachte (hoffte). Irgendwelche Vorschläge/Zeiger, wie könnte ich über das tun so gehen? Im Grunde, wenn eine Anfrage kommt, würde ich gerne auf die "Accept" - header und dann die Strecke wieder die Anfrage an die entsprechende API (aka Kolben-app). Es ist einfach die Anforderung abfangen können und schnappen Sie sich die header, aber dispatching, um die richtige version Kolben-app ist, wo ich bin ein bisschen verloren.
    • es gibt wirklich eine Menge Möglichkeiten, dies zu tun. Wenn Sie die verschiedenen Versionen als unterschiedliche Kolben-apps laufen auf dem gleichen Verfahren, dann eine WSGI-middleware sollte gut funktionieren. Die middleware verfügt über alle app-Instanzen und basiert auf den accept-header übergibt er die Anfrage an den richtigen.
    • Ja, die verschiedenen Versionen wären alle Kolben apps laufen im gleichen Prozess. Kennen Sie eine code-Beispiele zur Verfügung? Ich denke, ich bin gerade auf der Suche für how to pass entlang einer "Anfrage", um eine Kolben-app. Kolben ist meine erste unternehmung in WSGI Entwicklung.
    • es ist nicht genau das, was Sie wollen, aber diese Zeile von code zeigt, wie eine WSGI-middleware kann direkt eine Anfrage an den Kolben app. In Ihrem Fall haben Sie ein paar apps, die Sie wählen, welche um die Anfrage zu senden, um basierend auf dem Wert des Accept-headers, die Sie bekommen können von der environ Wörterbuch. Viel Glück!
    • sollte die Blaupause url_prefix werden /api/v1 ? wo soll die "api" - Teil gehen?
    • Ja, setzen Sie den gesamten Pfad bis zu der version in der url-Präfix ist eine gute Idee.

    InformationsquelleAutor Miguel
Schreibe einen Kommentar