API versiebeheer bij Workiva
Versiebeheer van API's (Application Programming Interface) is de kritische praktijk van het toewijzen van unieke identificaties aan verschillende iteraties van het ontwerp van een API om wijzigingen effectief te beheren en te communiceren. Het primaire doel hiervan is om achterwaartse compatibiliteit te behouden, zodat scripts en toepassingen die op een oudere versie vertrouwen niet kapot gaan wanneer er een nieuwe API-versie wordt uitgebracht. Dankzij deze stabiliteit kunnen API-aanbieders belangrijke updates, bugfixes en nieuwe functies introduceren zonder bestaande gebruikers te storen, waardoor consumenten de tijd en controle krijgen die nodig zijn om hun systemen te migreren wanneer ze er klaar voor zijn. Uiteindelijk bevordert goed API versiebeheer een betrouwbaar, schaalbaar en professioneel ontwikkelingsecosysteem.
2026-01-01 API versie uitgave
In januari 2026 zal Workiva een nieuwe API-versie uitbrengen, 2026-01-01. Deze nieuwe versie introduceert aanzienlijke verbeteringen op meerdere gebieden, waaronder verbeterde consistentie, nieuwe functionaliteit en afschrijving van oude functies. De voordelen van het upgraden naar de versie 2026-01-01 zijn onder andere voortdurende compatibiliteit met de nieuwste functies van het Workiva Platform, verbeterde beveiliging, verbeterde prestaties en de mogelijkheid om nieuwe functies te gebruiken.
Zie de Workiva API 2026-01-01 Upgradegids voor meer informatie over de nieuwe API-versie.
Afschaffing van API-versie 2022-01-01
Met de release van de 2026-01-01 versie zal de oudere 2022-01-01 versie in de deprecatiefase komen. Ondersteuning voor deze oudere versie zal doorgaan tot de vervaldatum in januari 2029, en ondersteuning voor de 2022-01-01 Prototype eindpunten zal eindigen in januari 2027.
Opmerking: De meeste Prototype-eindpunten in de versie 2022-01-01 zijn gepromoveerd naar General Availability (GA) in de versie 2026-01-01.
| Versie | Status | Type eindpunt | Datum zonsondergang |
|---|---|---|---|
| 2026-01-01 | Algemene beschikbaarheid (GA) | Alle | N.v.t. (huidig) |
| 2022-01-01 | Afgeschreven | Prototype | Januari 2027 |
| 2022-01-01 | Afgeschreven | GA | Januari 2029 |
API-versies vergelijken
Wanneer er een nieuwe versie wordt uitgebracht, bevat de API-documentatie voor die versie op de Workiva Developers Hub een Changelog sectie met gedetailleerde documentatie over API-veranderingen in die versie. De versie 2026-01-01 zal een 2026-01-01 Upgrade Guide sectie hebben met een volledig overzicht van de wijzigingen in die versie.
Daarnaast zijn er veel open source tools beschikbaar om een vergelijking uit te voeren op twee verschillende API-versies. Met dit soort hulpmiddelen kunnen versieveranderingen snel en gedetailleerd worden vergeleken. De open source tool oasdiff heeft een webgebaseerde Verschilcalculator waarmee u twee API versieconfiguratiebestanden (oas.yaml) kunt uploaden en een vergelijking kunt uitvoeren voor brekende wijzigingen, changelogs of een onbewerkte diff. Het kan resultaten uitvoeren in tekst, yaml, json, html en markdown.
Verwijzen naar een specifieke API-versie
Workiva API's maken gebruik van de X-Version header om aan te geven welke API versie gebruikt moet worden. Als de X-Version header niet wordt doorgegeven, wordt standaard de verouderde versie 2022-01-01 gebruikt.
Opmerking: Na januari 2029 zal de X-Version header vereist zijn en zullen alle API-aanroepen zonder deze header mislukken.
Om de versie in een API-verzoek via Python op te geven, neemt u het sleutel/waardepaar op in de headers van elk API-verzoek. Bijvoorbeeld: headers = {'X-Version': '2026-01-01'}
Momenteel kunt u 2026-01-01 of 2022-01-01 opgeven.
Aangezien er veel brekende veranderingen zijn in de versie 2026-01-01, is het van kritiek belang om ervoor te zorgen dat zowel de X-Version header is ingesteld voor de van toepassing zijnde versie als dat het API endpoint URL pad en parameters overeenkomen met de vereiste structuur van die versie. Daarnaast is het belangrijk om het responsformaat van de API-aanroep te begrijpen en eventuele verschillen in dat formaat tussen versies.
Voorbeelden
Voorbeeld van GET-verzoek
Hier een voorbeeld van het gebruik van een GET-verzoek in het eindpunt Een lijst met spreadsheets ophalen voor zowel de 2026-01-01- als de 2022-01-01-versie (deze voorbeelden bevatten het token van de drager als de tokenvariabele voor verduisteringsdoeleinden in dit artikel).
versie 2026-01-01
# 2026-01-01 versie # let op de X-Version header en de requests URL headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2026-01-01', } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, )versie 2022-01-01
# 2022-01-01 versie # let op de X-Version header en de 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, ) Voorbeeld van PATCH verzoek
Hieronder staat een voorbeeld van het gebruik van een PATCH-verzoek in het eindpunt Partially Update a Single Section voor zowel de 2026-01-01- als de 2022-01-01-versie (in deze voorbeelden is het token van de drager opgenomen als de tokenvariabele in dit artikel voor verduisteringsdoeleinden).
versie 2026-01-01
# 2026-01-01 versie # let op de X-Version header en de requests URL headers = { "Content-Type": "application/json", "Accept": "application/json", "Authorization":token, "X-Version": "2026-01-01", } patch_op = [ {"op":"replace","path":"/name","value":"Mijn nieuwe sectienaam" } ] resp = requests.patch ( https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) versie 2022-01-01
# 2022-01-01 versie # let op de X-Version header en de requests URL headers = { "Content-Type": "application/json", "Accept": "application/json", "Authorization": token, "X-Version": "2022-01-01", } patch_op = [ {"op":"replace","path":"/name","value":"Mijn nieuwe sectienaam" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) Tip: Zorg er niet alleen voor dat het URL-pad en de parameterstructuur overeenkomen met de toepasselijke API-versie, maar controleer ook de documentatie voor details over de beschikbare parameteropties.
Bijvoorbeeld, in het bovenstaande voorbeeld van het gedeeltelijk bijwerken van een enkele sectie, zijn er in de versie 2022-01-01 drie beschikbare padopties ( /name , /index , /parent ), maar in de versie 2026-01-01 zijn er meer dan dertig beschikbare padopties.
Beste praktijken voor scripting en API-versiebeheer
Hoewel de specifieke API-versie die u nodig hebt afhankelijk kan zijn van de status van actieve scripts en applicaties, tijdlijnen voor het upgraden naar de nieuwe API-versie, of andere factoren, volgen hieronder enkele best practices met betrekking tot scripting en API-versiebeheer.
Geef altijd de API-versie op
Vertrouw nooit op de standaardversie van een API-provider. Geef de versie expliciet op in elke API-aanroep. Door expliciet de versie op te geven, bepaalt u welke versie het script of de toepassing uitvoert.
De versie constant centraliseren
Definieer de API-versie als een enkele, gemakkelijk terug te vinden constante of configuratievariabele bovenaan uw script of in een apart configuratiebestand. Dit stroomlijnt probleemoplossing op betrouwbare wijze en verbetert de onderhoudbaarheid. Voorbeeld:
# config.py of bovenaan het hoofd script API_VERSION = '2026-01-01' # in een requests call headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, ) Vermijd het mengen van API-versies
Probeer niet om API-versies binnen één script of toepassing te mixen. Alle API-oproepen binnen één script of toepassing moeten verwijzen naar dezelfde Workiva API-versie (bijv. alle API-oproepen moeten de "2026-01-01" versie gebruiken). Het mengen van versies bemoeilijkt het debuggen, de aanvraagschema's en de antwoordformaten, waardoor het gedrag van het script onvoorspelbaar en het onderhoud ingewikkelder wordt.
API interactielogica isoleren
Maak een speciale module of set functies (vaak een "wrapper" of "client" genoemd) die alle communicatie met de externe API afhandelt. Dit patroon scheidt de "bedrijfslogica" van uw script van de "API-communicatielogica" Als de API verandert (bijv. de URL van het eindpunt of de request/response-structuur verandert in een nieuwe API-versie), hoeven alleen de wrapper-functies te worden bijgewerkt, niet het/de volledige script(s).
Deprecated eindpunten en parameters netjes afhandelen
Houd er bij het migreren van een oude API-versie naar een nieuwe rekening mee dat eindpunten en parameters hernoemd of verwijderd kunnen worden. Zorg ervoor dat uw script robuuste foutafhandeling en logboekregistratie bevat, omdat dit de best practices voor scriptontwikkeling ondersteunt en de kans vergroot dat versiegerelateerde fouten worden opgemerkt en gelogd.
Zie voor aanvullende informatie over best practices voor scripting het artikel Workiva Scripting: Best Practices voor ontwikkeling artikel.
Depreciatie bewaken en plannen
Workiva verschuift naar twee release windows per jaar voor nieuwe grote versies: lente en herfst. In het geval dat er geen brekende veranderingen zijn wanneer een releasedatum nadert en de release candidate voor die periode leeg is, zal Workiva op dat moment geen nieuwe versie van de API publiceren.
Wij raden u aan de website Workiva API Developer Hub actief te volgen, u te abonneren op Workiva Release Notes, en de gepubliceerde release- en deprecatieschema's te volgen. Scripts die een verouderde API-versie gebruiken, zullen uiteindelijk breken. Als u de vervaldatum (end-of-life) voor een API-versie kent, kunt u het noodzakelijke upgradewerk inplannen voordat de vervaldatum bereikt.
Scriptmigratie en -validatie
Om een naadloze migratie van API-versies te garanderen, stelt u een parallelle teststrategie op: kopieer het bestaande productiescript, pas alleen de kopie aan voor de nieuwe API-versie (inclusief alle vereiste wijzigingen aan headers, URL-pad en/of request/response-structuur) en test vervolgens zowel de oude als de nieuwe scripts om de functionaliteit en uitvoer te vergelijken en te controleren.
Door ze naast elkaar in een gecontroleerde omgeving uit te voeren, kunt u het stabiele oudere script als standaard gebruiken om te controleren en te verifiëren dat de functionaliteit en het resultaat van het nieuwe script identiek zijn, voordat u volledig overschakelt op de nieuwe versie en de oude versie afschaft.