API-Versionierung bei Workiva
Die Versionierung von Anwendungsprogrammierschnittstellen (API) ist eine wichtige Praxis, bei der verschiedenen Iterationen eines API-Designs eindeutige Identifikatoren zugewiesen werden, um Änderungen effektiv zu verwalten und zu kommunizieren. Ihr Hauptzweck ist die Aufrechterhaltung der Abwärtskompatibilität, um sicherzustellen, dass Skripte und Anwendungen, die auf eine ältere Version angewiesen sind, nicht kaputt gehen, wenn eine neue API-Version veröffentlicht wird. Diese Stabilität ermöglicht es API-Anbietern, wichtige Aktualisierungen, Fehlerbehebungen und neue Funktionen einzuführen, ohne die bestehenden Benutzer zu stören, so dass die Verbraucher die nötige Zeit und Kontrolle haben, um ihre Systeme zu migrieren, wenn sie dazu bereit sind. Letztlich fördert eine angemessene API-Versionierung ein zuverlässiges, skalierbares und professionelles Entwicklungs-Ökosystem.
2026-01-01 Veröffentlichung der API-Version
Im Januar 2026 wird Workiva eine neue API-Version veröffentlichen, 2026-01-01. Diese neue Version enthält signifikante Verbesserungen in mehreren Bereichen, einschließlich verbesserter Konsistenz, neuer Funktionen und der Abschaffung von Legacy-Funktionen. Zu den Vorteilen eines Upgrades auf die Version 2026-01-01 gehören die fortgesetzte Kompatibilität mit den neuesten Funktionen der Workiva-Plattform, die verbesserte Sicherheit, die verbesserte Leistung und die Möglichkeit, neue Funktionen zu nutzen.
Weitere Informationen über die neue API-Version finden Sie im Workiva API 2026-01-01 Upgrade Guide.
Ablehnung der API-Version 2022-01-01
Mit der Veröffentlichung der Version 2026-01-01 tritt die ältere Version 2022-01-01 in die Verwerfungsphase ein. Der Support für diese ältere Version wird bis zu ihrem Auslaufen im Januar 2029 fortgesetzt, und der Support für die 2022-01-01 Prototyp-Endpunkte endet im Januar 2027.
Hinweis: Die meisten Prototyp-Endpunkte in der Version 2022-01-01 wurden in der Version 2026-01-01 zur allgemeinen Verfügbarkeit (GA) befördert.
| Finale | Status | Endpunkt-Typ | Datum des Sonnenuntergangs |
|---|---|---|---|
| 2026-01-01 | Allgemeine Verfügbarkeit (GA) | Alle | N/A (Aktuell) |
| 2022-01-01 | Veraltet | Prototyp | Januar 2027 |
| 2022-01-01 | Veraltet | GA | Januar 2029 |
Vergleich von API-Versionen
Wenn eine neue Version veröffentlicht wird, enthält die API-Dokumentation für diese Version auf dem Workiva Developers Hub einen Changelog-Abschnitt mit einer detaillierten Dokumentation der API-Änderungen in dieser Version. Für die Version 2026-01-01 gibt es einen Abschnitt 2026-01-01 Upgrade Guide mit einer vollständigen Übersicht über die Änderungen in dieser Version.
Außerdem gibt es viele Open-Source-Tools, mit denen Sie einen Vergleich zwischen zwei verschiedenen API-Versionen durchführen können. Diese Art von Tools ermöglicht einen schnellen und detaillierten Vergleich von Versionsänderungen. Das Open-Source-Tool oasdiff verfügt über einen webbasierten Diff-Rechner, mit dem Sie zwei API-Versionskonfigurationsdateien (oas.yaml) hochladen und einen Vergleich für Breaking Changes, Changelogs oder einen Raw Diff durchführen können. Die Ergebnisse können in den Formaten text, yaml, json, html und markdown ausgegeben werden.
Eine bestimmte API-Version referenzieren
Workiva-APIs verwenden den X-Version Header, um die zu verwendende API-Version anzugeben. Wenn der X-Version-Header nicht übergeben wird, wird standardmäßig die veraltete Version 2022-01-01 verwendet.
Hinweis: Nach Januar 2029 wird der X-Version-Header erforderlich sein und alle API-Aufrufe ohne ihn werden fehlschlagen.
Um die Version in einer API-Anfrage über Python anzugeben, fügen Sie das Schlüssel/Wert-Paar in die Header für jede API-Anfrage ein. Zum Beispiel: headers = {'X-Version': '2026-01-01'}
Zurzeit können Sie entweder 2026-01-01 oder 2022-01-01 angeben.
Da die Version 2026-01-01 viele wichtige Änderungen enthält, müssen Sie sicherstellen, dass der X-Version-Header für die entsprechende Version gesetzt ist und dass der Pfad und die Parameter der API-Endpunkt-URL mit der erforderlichen Struktur der Version übereinstimmen. Außerdem ist es wichtig, das Antwortformat des API-Aufrufs und mögliche Unterschiede in diesem Format zwischen den Versionen zu kennen.
Beispiele
Beispiel für eine GET-Anfrage
Hier ein Beispiel für die Verwendung einer GET-Anfrage im Endpunkt Retrieve a List of Spreadsheets sowohl für die Version 2026-01-01 als auch für die Version 2022-01-01 (diese Beispiele enthalten das Bearer-Token als Token-Variable für die Verschleierung in diesem Artikel).
2026-01-01 Version
# Version 2026-01-01 # beachten Sie den X-Version-Header und die URL der Anfrage headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2026-01-01', } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, )2022-01-01 Version
# Version 2022-01-01 # beachten Sie den X-Version-Header und die URL der Anfrage headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } resp = requests.get( 'https://api.app.wdesk.com/platform/v1/spreadsheets', headers = headers, ) Beispiel für eine PATCH-Anfrage
Nachfolgend sehen Sie ein Beispiel für die Verwendung einer PATCH-Anfrage im Endpunkt Partially Update a Single Section sowohl für die Version 2026-01-01 als auch für die Version 2022-01-01 (in diesen Beispielen wird das Inhaber-Token in diesem Artikel zur Verschleierung als Token-Variable verwendet).
2026-01-01 Version
# Version 2026-01-01 # beachten Sie den X-Version-Header und die URL der Anfragen headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization':token, 'X-Version': '2026-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "Mein neuer Sektionsname" } ] resp = requests.patch ( https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) 2022-01-01 Version
# Version 2022-01-01 # Beachten Sie den X-Version-Header und die URL der Anfragen headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "Mein neuer Sektionsname" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) Tipp: Vergewissern Sie sich nicht nur, dass der URL-Pfad und die Parameterstruktur mit der jeweiligen API-Version übereinstimmen, sondern lesen Sie auch in der Dokumentation nach, um sich über die verfügbaren Parameteroptionen zu informieren.
Im obigen Beispiel für die teilweise Aktualisierung eines einzelnen Abschnitts gibt es in der Version 2022-01-01 drei verfügbare Pfadoptionen ( /name , /index , /parent ), aber in der Version 2026-01-01 gibt es über dreißig verfügbare Pfadoptionen.
Bewährte Praktiken für Skripting und API-Versionen
Die von Ihnen benötigte API-Version kann vom Status aktiver Skripte und Anwendungen, von den Fristen für das Upgrade auf die neue API-Version oder von anderen Faktoren abhängen. Im Folgenden finden Sie einige bewährte Verfahren für die Skripterstellung und API-Versionierung.
Geben Sie immer die API-Version an
Verlassen Sie sich niemals auf die Standardversion eines API-Anbieters. Geben Sie die Version bei jedem API-Aufruf explizit an. Indem Sie die Version explizit angeben, haben Sie die Kontrolle darüber, welche Version das Skript oder die Anwendung ausführt.
Zentralisieren Sie die Versionskonstante
Definieren Sie die API-Version als eine einzige, leicht auffindbare Konstante oder Konfigurationsvariable am Anfang Ihres Skripts oder in einer separaten Konfigurationsdatei. Dies vereinfacht zuverlässig die Fehlersuche und verbessert die Wartbarkeit. Beispiel:
# config.py oder am Anfang des Hauptskripts API_VERSION = '2026-01-01' # in einem requests-Aufruf headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, ) Vermeiden Sie das Mischen von API-Versionen
Versuchen Sie nicht, API-Versionen innerhalb eines einzelnen Skripts oder einer einzelnen Anwendung zu mischen. Alle API-Aufrufe innerhalb eines Skripts oder einer Anwendung sollten auf dieselbe Workiva API-Version verweisen (z.B. sollten alle API-Aufrufe die Version "2026-01-01" verwenden). Das Mischen von Versionen erschwert die Fehlersuche, Anfrageschemata und Antwortformate, wodurch das Verhalten des Skripts unvorhersehbar und die Wartung komplizierter wird.
API-Interaktionslogik isolieren
Erstellen Sie ein spezielles Modul oder eine Reihe von Funktionen (oft als "Wrapper" oder "Client" bezeichnet), das bzw. die die gesamte Kommunikation mit der externen API übernimmt. Dieses Muster trennt die "Geschäftslogik" Ihres Skripts von der "API-Kommunikationslogik". Wenn sich die API ändert (z.B. die Endpunkt-URL oder die Anfrage-/Antwortstruktur ändert sich in einer neuen API-Version), müssen nur die Wrapper-Funktionen aktualisiert werden, nicht das/die gesamte(n) Skript(e).
Ordentlicher Umgang mit veralteten Endpunkten und Parametern
Rechnen Sie bei der Migration von einer alten zu einer neuen API-Version damit, dass Endpunkte und Parameter umbenannt oder entfernt werden können. Stellen Sie sicher, dass Ihr Skript eine robuste Fehlerbehandlung und -protokollierung enthält, da dies die Best Practices für die Skriptentwicklung unterstützt und die Wahrscheinlichkeit erhöht, dass versionsbezogene Fehler abgefangen und protokolliert werden.
Weitere Informationen zu bewährten Praktiken bei der Skripterstellung finden Sie im Artikel Workiva Scripting: Bewährte Praktiken bei der Entwicklung .
Überwachen und planen Sie die Abkündigung
Workiva geht dazu über, zwei Veröffentlichungszeiträume pro Jahr für neue Hauptversionen anzubieten: Frühjahr und Herbst. Falls es keine bahnbrechenden Änderungen gibt, wenn ein Veröffentlichungsdatum naht und der Release Candidate für diesen Zeitraum leer ist, wird Workiva zu diesem Zeitpunkt keine neue Version der API veröffentlichen.
Wir empfehlen Ihnen, die Website Workiva API Developer Hub aktiv zu verfolgen, die Workiva Release Notes zu abonnieren und die veröffentlichten Release- und Deprecation-Zeitpläne zu beachten. Skripte, die eine veraltete API-Version verwenden, werden irgendwann nicht mehr funktionieren. Wenn Sie das Enddatum einer API-Version kennen, können Sie die notwendigen Aktualisierungsarbeiten vor dem Enddatum planen.
Skript-Migration und Validierung
Um eine nahtlose Migration der API-Version zu gewährleisten, sollten Sie eine parallele Teststrategie einführen: Kopieren Sie das vorhandene Produktionsskript, ändern Sie nur die Kopie, um die neue API-Version zu erreichen (einschließlich aller erforderlichen Änderungen an den Headern, dem URL-Pfad und/oder der Anfrage-/Antwortstruktur), und testen Sie dann sowohl das alte als auch das neue Skript, um Funktionalität und Ausgabe zu vergleichen und zu überprüfen.
Indem Sie die beiden Skripte in einer kontrollierten Umgebung nebeneinander laufen lassen, können Sie das stabile ältere Skript als Standard verwenden, um zu überwachen und zu überprüfen, dass die Funktionalität und das Ergebnis des neuen Skripts identisch sind, bevor Sie vollständig auf die neue Version umstellen und die alte Version verwerfen.