Versionering av API på Workiva
Versionering av API:er (Application Programming Interface) är en viktig metod för att tilldela unika identifierare till olika iterationer av ett API:s design för att hantera och kommunicera ändringar på ett effektivt sätt. Dess främsta syfte är att upprätthålla bakåtkompatibilitet, vilket säkerställer att skript och applikationer som förlitar sig på en äldre version inte bryts när en ny API-version släpps. Denna stabilitet gör det möjligt för API-leverantörer att införa större uppdateringar, buggfixar och nya funktioner utan att störa befintliga användare, vilket ger konsumenterna den tid och kontroll som krävs för att migrera sina system när de är redo. I slutändan främjar korrekt API-versionering ett tillförlitligt, skalbart och professionellt utvecklingsekosystem.
2026-01-01 API Version Release
I januari 2026 kommer Workiva att släppa en ny API-version, 2026-01-01. Denna nya version innehåller betydande förbättringar inom flera områden, inklusive förbättrad konsekvens, nya funktioner och borttagande av äldre funktioner. Fördelarna med att uppgradera till version 2026-01-01 inkluderar fortsatt kompatibilitet med de senaste funktionerna i Workiva Platform, förbättrad säkerhet, förbättrad prestanda och möjligheten att utnyttja nya funktioner.
För ytterligare information om den nya API-versionen, se Workiva API 2026-01-01 Upgrade Guide.
Avskaffande av 2022-01-01 API-version
Med lanseringen av 2026-01-01-versionen kommer den äldre 2022-01-01-versionen att gå in i sin avvecklingsfas. Support för denna äldre version kommer att fortsätta tills den upphör i januari 2029, och support för 2022-01-01 Prototype endpoints upphör i januari 2027.
Obs: De flesta prototypändpunkterna i versionen 2022-01-01 har flyttats till allmän tillgänglighet (GA) i versionen 2026-01-01.
| Version | Status | Typ av slutpunkt | Datum för solnedgång |
|---|---|---|---|
| 2026-01-01 | Allmän tillgänglighet (GA) | Alla | N/A (nuvarande) |
| 2022-01-01 | Föråldrad | Prototyp | Januari 2027 |
| 2022-01-01 | Föråldrad | GA | Januari 2029 |
Jämförelse av API-versioner
När en ny version släpps innehåller API-dokumentationen för den versionen på Workiva Developers Hub ett Changelog-avsnitt som innehåller detaljerad dokumentation om API-ändringar i den versionen. Versionen 2026-01-01 kommer att ha en 2026-01-01 Upgrade Guide sektion med en fullständig genomgång av ändringarna i den versionen.
Dessutom finns det många verktyg med öppen källkod som kan användas för att göra en jämförelse mellan två olika API-versioner. Dessa typer av verktyg möjliggör snabba och detaljerade jämförelser av versionsändringar. Open source-verktyget oasdiff har en webbaserad Diff Calculator som gör att du kan ladda upp två API-versionskonfigurationsfiler (oas.yaml) och köra en jämförelse för brytande ändringar, changelogs eller en rå diff. Den kan mata ut resultat i text, yaml, json, html och markdown.
Hänvisa till en specifik API-version
Workiva API:er utnyttjar X-Version för att ange vilken API-version som ska användas. Om X-Version-rubriken inte skickas med är standardversionen den föråldrade versionen 2022-01-01.
Obs: Efter januari 2029 kommer X-Version-headern att krävas och alla API-anrop utan den kommer att misslyckas.
Om du vill ange versionen i en API-begäran via Python inkluderar du nyckel/värde-paret i rubrikerna för varje API-begäran. Till exempel: headers = {'X-Version': '2026-01-01'}
För närvarande kan du ange antingen 2026-01-01 eller 2022-01-01.
Eftersom det finns många förändringar i version 2026-01-01 är det viktigt att se till att X-Version-rubriken är inställd för den tillämpliga versionen och att API-slutpunktens URL-sökväg och parametrar matchar den struktur som krävs för den versionen. Dessutom är det viktigt att förstå svarsformatet för API-anropet och eventuella skillnader i det formatet mellan olika versioner.
Exempel
Exempel på GET-begäran
Här är ett exempel på användning av en GET-begäran i slutpunkten Retrieve a List of Spreadsheets för både versionerna 2026-01-01 och 2022-01-01 (i dessa exempel ingår bearer-token som tokenvariabel för fördunklingsändamål i den här artikeln).
2026-01-01 version
# 2026-01-01 version # notera X-Version-headern och requests URL 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
# 2022-01-01 version # notera X-Version-headern och requests URL headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } resp = requests.get( 'https://api.app.wdesk.com/platform/v1/spreadsheets', headers = headers, ) Exempel på PATCH-begäran
Nedan följer ett exempel på användning av en PATCH-begäran i ändpunkten Partially Update a Single Section för både versionerna 2026-01-01 och 2022-01-01 (i dessa exempel ingår bearer-token som tokenvariabel i den här artikeln för fördunklingsändamål).
2026-01-01 version
# 2026-01-01 version # notera X-Version-headern och förfrågningarnas URL headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization':token, "X-Version": "2026-01-01", } patch_op = [ { { "op": "replace", "path": "/name", "value": "Mitt nya sektionsnamn" } ] resp = requests.patch ( https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) 2022-01-01 version
# 2022-01-01 version # notera X-Version-huvudet och förfrågningarnas URL headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': token, "X-Version": "2022-01-01", } patch_op = [ { { "op": "replace", "path": "/name", "value": "Mitt nya sektionsnamn" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) Tips: Förutom att säkerställa att URL-sökvägen och parameterstrukturen överensstämmer med den tillämpliga API-versionen, bör du kontrollera dokumentationen för detaljer om de tillgängliga parameteralternativen.
I exemplet Delvis uppdatering av ett enskilt avsnitt ovan finns det till exempel tre tillgängliga sökvägsalternativ i versionen 2022-01-01 (/namn , /index , /förälder), men i versionen 2026-01-01 finns det över trettio tillgängliga sökvägsalternativ.
Bästa praxis för skriptning och API-versionering
Den specifika API-version du behöver kan bero på statusen för aktiva skript och applikationer, tidsramar för uppgradering till den nya API-versionen eller andra faktorer, men nedan följer några bästa metoder för skript och API-versionering.
Ange alltid API-versionen
Förlita dig aldrig på en API-leverantörs standardversion. Ange versionen explicit i varje API-anrop. Genom att uttryckligen ange versionen har du kontroll över vilken version som skriptet eller programmet körs i.
Centralisera versionskonstanten
Definiera API-versionen som en enda konstant eller konfigurationsvariabel som är lätt att hitta längst upp i skriptet eller i en separat konfigurationsfil. Detta effektiviserar felsökningen på ett tillförlitligt sätt och förbättrar underhållsmöjligheterna. Exempel:
# config.py eller högst upp i huvudskriptet API_VERSION = '2026-01-01' # i ett requests-anrop headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, ) Undvik att blanda API-versioner
Försök inte att blanda API-versioner i ett och samma skript eller program. Alla API-anrop inom ett enda skript eller en enda applikation ska referera till samma Workiva API-version (t.ex. alla API-anrop ska använda versionen "2026-01-01"). Att blanda versioner försvårar felsökning, begärandescheman och svarsformat, vilket gör skriptets beteende oförutsägbart och underhållet mer komplicerat.
Isolera API-interaktionslogik
Skapa en särskild modul eller uppsättning funktioner (ofta kallad "wrapper" eller "client") som hanterar all kommunikation med det externa API:et. Detta mönster separerar "affärslogiken" i ditt skript från "API-kommunikationslogiken" Om API:et ändras (t.ex. om URL:en till slutpunkten eller strukturen för begäran/svar ändras i en ny API-version) behöver endast omslagsfunktionerna uppdateras, inte hela skriptet.
Hantera föråldrade slutpunkter och parametrar på ett smidigt sätt
När du migrerar från en gammal API-version till en ny måste du räkna med att ändpunkter och parametrar kan byta namn eller tas bort. Se till att ditt skript innehåller robust felhantering och loggning, eftersom detta stöder bästa praxis för skriptutveckling och ökar sannolikheten för att versionsrelaterade fel upptäcks och loggas.
Mer information om bästa praxis för skript finns i artikeln Workiva Scripting: Bästa metoder för utveckling artikel.
Övervaka och planera för utfasning
Workiva övergår till att tillhandahålla två releasefönster per år för nya större versioner; vår och höst. I händelse av att det inte finns några avgörande ändringar när ett utgivningsdatum närmar sig och utgivningskandidaten för den perioden är tom, kommer Workiva inte att publicera en ny version av API:et vid den tidpunkten.
Vi rekommenderar att du aktivt följer webbplatsen Workiva API Developer Hub, prenumererar på Workiva Release Notes och följer de publicerade release- och deprecationsscheman. Skript som använder en föråldrad API-version kommer så småningom att gå sönder. Om du känner till slutdatumet för en API-version kan du schemalägga det nödvändiga uppgraderingsarbetet före slutdatumet.
Migrering och validering av skript
För att säkerställa en sömlös migrering av API-versioner bör du upprätta en parallell teststrategi: kopiera det befintliga produktionsskriptet, modifiera endast kopian för att rikta in sig på den nya API-versionen (inklusive eventuella nödvändiga ändringar av rubriker, URL-sökväg och/eller begäran/svar-struktur) och testa sedan både det gamla och det nya skriptet för att jämföra och verifiera funktionalitet och resultat.
Genom att köra dem sida vid sida i en kontrollerad miljö kan du använda det stabila äldre skriptet som standard för att övervaka och verifiera att funktionaliteten och resultatet som produceras av det nya skriptet är identiska innan du helt går över till den nya versionen och avregistrerar den gamla versionen.