API-Versionierung mit dem Django Rest Framework

drf 3

DRF
Eine schnelle Google-Suche nach „REST API-Versionierung“ liefert zahlreiche Diskussionen darüber, wie eine Version in der Anfrage angegeben werden sollte. Es gibt zahlreiche leidenschaftliche Debatten über RESTful-Prinzipien und die Vor- und Nachteile, ob das Einbetten von Versionsnummern in URLs, die Verwendung benutzerdefinierter Anfrage-Header oder die Nutzung des vorhandenen Accept-Headers die beste Lösung ist. Leider gibt es keine eine richtige Antwort, die alle zufriedenstelltUnabhängig davon, welchen Ansatz Sie letztendlich wählen, werden einige behaupten, dass Sie es falsch machen. Unabhängig vom verwendeten Ansatz stellt sich, sobald die Version aus der Anfrage analysiert wurde, eine weitere, größere Frage: Wie sollten Sie Ihren API-Code verwalten, um die verschiedenen Schemata der verschiedenen Versionen zu unterstützen? Überraschenderweise gibt es kaum Diskussionen darüber, wie dies am besten erreicht werden kann.
Bei Rescale haben wir unsere API mit der Django-Rest-FrameworkDie kommende Version 3.1 wird Unterstützung für die API-Versionierung bieten. Die Projektleitung hat sich klugerweise entschieden, die Versionsdebatte zu umgehen, indem sie ein Framework bereitstellt, das API-Entwicklern die Wahl zwischen verschiedenen Strategien zur Angabe der Version in der Anfrage ermöglicht. Es gibt jedoch kaum offizielle Richtlinien zum Umgang mit dieser Version im Code. Tatsächlich wird in der Dokumentation das Problem größtenteils nur umgangen, indem erklärt wird: „Wie Sie Ihr Verhalten variieren, bleibt Ihnen überlassen.“
Einer der Stripe-Ingenieure hat einen netten Beitrag gepostet Zusammenfassung auf hoher Ebene wie Stripe mit der Abwärtskompatibilität seiner API umgeht. Der Autor beschreibt eine Transformationspipeline, durch die Anfragen und Antworten geleitet werden. Einer der Hauptvorteile dieses Ansatzes besteht darin, dass die Kernlogik der API immer mit der aktuellen Version der API arbeitet und es separate „Kompatibilitätsebenen“ für die verschiedenen Versionen gibt. Anfragen vom Client durchlaufen eine „Anforderungskompatibilitätsebene“, um sie in das aktuelle Schema zu transformieren, bevor sie an die Kernlogik der API übergeben werden. Antworten der Kernlogik der API werden durch eine „Antwortkompatibilitätsebene“ geleitet, um die Antwort in das Schemaformat der angeforderten Version herunterzustufen.
In diesem Beitrag möchte ich einen möglichen Ansatz zur Unterstützung dieser Art von Transformationspipeline mit DRF untersuchen. Der naheliegende Ort für die Einbindung der Transformationslogik in DRF ist der Serializer, da dieser sowohl an der Validierung der Anforderungsdaten (Serializer.to_internal_value) als auch an der Vorbereitung der Antwortdaten für die Rückgabe von einer APIView-Methode (Serializer.to_representation) beteiligt ist.
Die Grundidee besteht darin, eine geordnete Reihe von Transformationen zu erstellen, die auf Anforderungsdaten angewendet werden, um sie in das aktuelle Schema zu konvertieren. Analog dazu werden Antwortdaten in umgekehrter Reihenfolge durch die Transformationen geleitet, um die Daten im aktuellen Schema in die vom Client angeforderte Version zu konvertieren. Dies ähnelt stark den Vorwärts- und Rückwärtsmethoden bei Datenbankmigrationen.
Als einfaches Beispiel für die Verwendung einer Antworttransformation ist im Folgenden ein einfacher Serialisierer dargestellt, der den Namen einer Mailingliste und eine Liste mit den E-Mail-Adressen der Abonnenten zurückgibt:

Klasse MailingListSerializer (Serializer.ModelSerializer): Abonnenten = Serializer.SerializerMethodField ('_subscribers') def _subscribers (self, obj): return [s.email für s in obj.subscribers_set.all ()] Klasse Meta: Modell = Modelle.MailingList-Felder = ('Name', 'Beschreibung', 'Abonnenten')

Die Nutzlast eines Endpunkts, der diesen Serialisierer verwendet, gibt möglicherweise JSON im folgenden Format zurück:

{'name': 'Katzenfakten', 'description': 'Wissenswertes über Katzen', 'subscribers': ['joe@email.com', 'jane@email.com']}

Einige Zeit später entscheiden wir, dass dieser Endpunkt auch das Datum zurückgeben muss, an dem sich jeder Abonnent für die Mailingliste angemeldet hat. Dies stellt eine grundlegende Änderung für alle Clients dar, die die ursprüngliche Version der API verwenden, da jedes Element im Abonnenten-Array nun ein Objekt statt einer einfachen Zeichenfolge ist:

{'name': 'Katzenfakten', 'description': 'Wissenswertes über Katzen', 'subscribers': [ {'email': 'joe@email.com', 'date_subscribed': '2015-01-15T00:01:34Z'}, {'email': 'jane@email.com', 'date_subscribed': '2015-02-18T04:57:56Z'} ]}

Der Serialisierer muss aktualisiert werden, um Daten in diesem neuen Format zurückzugeben. Um die Abwärtskompatibilität mit der ursprünglichen API-Version zu gewährleisten, muss er außerdem so geändert werden, dass er von einer VersioningMixin-Klasse abgeleitet wird und den Speicherort der Transform-Klassen angibt (mehr dazu in Kürze):

Klasse MailingListSerializer (VersioningMixin, Serialisierer.ModelSerializer): transform_base = „api.transforms.mailinglist.MailingListSerializerTransform“ Abonnenten = Serialisierer.SerializerMethodField („_Abonnenten“) def _Abonnenten (selbst, Objekt): return [{„E-Mail“: s.E-Mail, „Datum_abonniert“: s.Datum_abonniert} für s in Objekt.Abonnenten_set.all()] Klasse Meta: Modell = Modelle.MailingList-Felder = („Name“, „Abonnenten“)

Bei jeder neuen API-Version für diesen Serialisierer muss dem Modul api.transforms.mailinglist eine neue nummerierte Transform-Klasse hinzugefügt werden. Jeder Transform verarbeitet das Downgrade von Version N auf Version N-1 durch die Anpassung des Antwortdaten-Dicts:

Klasse MailingListSerializerTransform0001(Transform): def update_response_data(self, data, request, source): # Transformiert ein rohes v2-Eingabewörterbuch in ein v1-Wörterbuch data['subscribers'] = [s['email'] für s in data['subscribers']]

Die Transform-Klasse entspricht einer Schemamigration und enthält Methoden zur Transformation von Anforderungs- und Antwortdaten. Jeder Transform-Klassenname muss einen numerischen Wert als Suffix haben. Die VersioningMixin-Klasse verwendet diesen, um die Reihenfolge zu bestimmen, in der Transforms auf die Anforderungs- oder Antwortdaten angewendet werden sollen.

Klasse Transform(Objekt): def update_request_data(selbst, Daten, Anfrage): """Daten sind das native Dict, das die Ausgabe der Analyse der Anfrage vom Client ist. """ Pass def update_response_data(selbst, Daten, Anfrage, Quelle): """Daten sind das native Dict, das an den Renderer übergeben und an den Client zurückgegeben wird. Quelle ist das Originalobjekt, das in ein natives Dict konvertiert wird. """ Pass

Die Klasse VerisoningMixin bietet die Überschreibungen Serializer.to_internal_value und Serializer.to_representation. Diese suchen die Transformationen, auf die die transform_base-Eigenschaft des Serialisierers verweist, und wenden sie an, um Anfragen in die aktuelle API-Version zu konvertieren oder Antworten von der aktuellen API-Version auf die angeforderte Version herunterzustufen. Im folgenden Codeausschnitt verweist settings.API_VERSION auf die neueste, aktuelle API-Versionsnummer und das Feld request.version wird auf die vom Client angeforderte API-Version gesetzt:

Klasse VersioningMixin (Objekt): def to_internal_value (selbst, Daten, *Argumente, **kwargs): """Wendet eine Pipeline von Transformationen auf die angegebenen Anforderungsdaten an, bis diese auf die aktuelle API-Version aktualisiert werden. """ wenn Daten: Anforderung = self.context['Anforderung'] für v im Bereich (Anforderung.Version, Einstellungen.API_VERSION): self._get_transform(v).update_request_data(Daten, Anforderung) gibt super zurück (VersioningMixin, selbst).to_internal_value (Daten, *Argumente, **kwargs) def to_representation (selbst, Objekt, *Argumente, **kwargs): """Wendet eine Pipeline von Transformationen auf die angegebenen Antwortdaten an, bis diese auf die gewünschte API-Version heruntergestuft werden. """ Daten = super (VersioningMixin, selbst).to_representation (Objekt, *Argumente, **kwargs) wenn Objekt: Anforderung = self.context['request'] für v im Bereich (settings.API_VERSION, request.version, -1): t = self._get_transform(v - 1) t.update_response_data(data, request, obj) return data def _get_transform(self, version): transform_dict = {v: c für v, c in self._transform_classes()} TransformKlass = transform_dict.get(version, Transform) return TransformKlass() def _transform_classes(self): module, base = self.transform_base.rsplit('.', 1) mod = import_module(module) für Name, Klass in inspect.getmembers(mod): wenn name.startswith(base) und issubclass(Klass, Transform): m = re.search('\d+ Der Hauptvorteil dieses Ansatzes ist, dass die APIView (die Klassen, die im Allgemeinen die Kern-API-Logik implementieren und Serialisierer für die Anfrage-/Antwortverarbeitung verwenden) nur Sorgen Sie sich nicht um die neueste Schemaversion. Darüber hinaus erfordert das Schreiben einer Transformation Kenntnis der aktuellen und vorherigen Version der API. Beim Erstellen von Version 10 einer bestimmten Antwort muss nur eine einzige Transformation zwischen v10 und v9 erstellt werden. Eine Anfrage nach v7 wird zunächst durch die neue Transformation von v10 auf v9 transformiert. Die bestehenden Transformationen von v9 auf v8 und v8 auf v7 erledigen den Rest. Wir glauben nicht, dass dies ein Allheilmittel für alle auftretenden Abwärtskompatibilitätsprobleme ist. Es gibt sicherlich einige Leistungsprobleme, die zu berücksichtigen sind, wenn Anfragen und Antworten ständig durch eine Reihe potenziell kostspieliger Transformationen laufen müssen. Ebenso wie es manchmal unmöglich ist, Rückwärtsmigrationen für Datenbankschemaänderungen zu erstellen, gibt es sicherlich komplexere API-Änderungen, die mit diesem Ansatz nicht einfach gelöst werden können. Für grundlegende API-Änderungen scheint dies jedoch eine gute Möglichkeit zu sein, Probleme zu isolieren und die Einbettung von bedingtem Goop in die API-Kernlogik für Versionierungszwecke zu vermeiden. , Name) if m: yield (int(m.group(0)), Klasse)

Der Hauptvorteil dieses Ansatzes besteht darin, dass sich die APIView (die Klassen, die im Allgemeinen die Kernlogik der API implementieren und Serialisierer für die Anfrage-/Antwortverarbeitung verwenden) nur um die neueste Schemaversion kümmern muss. Darüber hinaus erfordert das Schreiben einer Transformation nur Kenntnisse der aktuellen und vorherigen Version der API. Beim Erstellen von Version 10 einer bestimmten Antwort muss nur eine einzige Transformation zwischen v10 und v9 erstellt werden. Eine Anfrage nach v7 wird zunächst durch die neue Transformation von v10 nach v9 transformiert. Die vorhandenen Transformationen von v9 nach v8 und v8 nach v7 erledigen den Rest.
Wir glauben nicht, dass dies ein Allheilmittel für alle auftretenden Abwärtskompatibilitätsprobleme ist. Es gibt sicherlich einige Leistungsprobleme, die durch die ständige Ausführung von Anfragen und Antworten durch eine Reihe potenziell kostspieliger Transformationen zu berücksichtigen sind. Ebenso wie es manchmal unmöglich ist, Rückwärtsmigrationen für Datenbankschemaänderungen zu erstellen, gibt es sicherlich auch komplexere API-Änderungen, die mit diesem Ansatz nicht einfach zu beheben sind. Für grundlegende API-Änderungen scheint dies jedoch eine gute Möglichkeit zu sein, Probleme zu isolieren und die Einbettung von bedingtem Goop in die API-Kernlogik zu Versionierungszwecken zu vermeiden.