API-versjonering hos Workiva
Versjonering av programmeringsgrensesnitt (API) er den kritiske praksisen med å tildele unike identifikatorer til ulike iterasjoner av et APIs design for å administrere og kommunisere endringer på en effektiv måte. Hovedformålet er å opprettholde bakoverkompatibilitet, slik at skript og programmer som er avhengige av en eldre versjon, ikke går i stykker når en ny API-versjon lanseres. Denne stabiliteten gjør det mulig for API-leverandører å introdusere større oppdateringer, feilrettinger og nye funksjoner uten å forstyrre eksisterende brukere, noe som gir forbrukerne tid og kontroll til å migrere systemene sine når de er klare. Til syvende og sist bidrar riktig API-versjonering til et pålitelig, skalerbart og profesjonelt utviklingsøkosystem.
2026-01-01-01 Utgivelse av API-versjon
I januar 2026 vil Workiva lansere en ny API-versjon, 2026-01-01. Denne nye versjonen innebærer betydelige forbedringer på flere områder, blant annet bedre konsistens, ny funksjonalitet og utfasing av eldre funksjoner. Fordelene med å oppgradere til versjon 2026-01-01 inkluderer fortsatt kompatibilitet med de nyeste funksjonene på Workiva-plattformen, forbedret sikkerhet, forbedret ytelse og muligheten til å utnytte nye funksjoner.
For mer informasjon om den nye API-versjonen, se Workiva API 2026-01-01 Upgrade Guide.
Utfasing av 2022-01-01 API-versjon
Med lanseringen av 2026-01-01-versjonen vil den eldre 2022-01-01-versjonen gå inn i utfasingsfasen. Støtten for denne eldre versjonen vil fortsette frem til den utløper i januar 2029, og støtten for 2022-01-01 Prototype-endepunktene vil opphøre i januar 2027.
Merk: De fleste prototypendepunktene i 2022-01-01-versjonen har blitt forfremmet til generell tilgjengelighet (GA) i 2026-01-01-versjonen.
| Versjon | Status | Type endepunkt | Dato for solnedgang |
|---|---|---|---|
| 2026-01-01 | Generell tilgjengelighet (GA) | Alle | N/A (Gjeldende) |
| 2022-01-01 | Foreldet | Prototype | Januar 2027 |
| 2022-01-01 | Foreldet | GA | Januar 2029 |
Sammenligning av API-versjoner
Når en ny versjon lanseres, inneholder API-dokumentasjonen for den aktuelle versjonen på Workiva Developers Hub en Changelog-seksjon som inneholder detaljert dokumentasjon om API-endringene i den aktuelle versjonen. Versjonen 2026-01-01 vil ha en 2026-01-01 Upgrade Guide -seksjon med en fullstendig gjennomgang av endringene i den versjonen.
I tillegg finnes det mange verktøy med åpen kildekode som kan brukes til å sammenligne to ulike API-versjoner. Denne typen verktøy gjør det mulig å foreta raske og detaljerte sammenligninger av versjonsendringer. Verktøyet med åpen kildekode oasdiff har en nettbasert Diff Calculator som lar deg laste opp to API-versjonskonfigurasjonsfiler (oas.yaml) og kjøre en sammenligning for å se etter endringer, endringslogger eller en rå diff. Den kan skrive ut resultater i tekst, yaml, json, html og markdown.
Referere til en bestemt API-versjon
Workiva API-er utnytter X-Version header for å spesifisere hvilken API-versjon som skal brukes. Hvis X-Version-headeren ikke sendes, er standardversjonen den utdaterte 2022-01-01-versjonen.
Merk: Etter januar 2029 vil X-Version-overskriften være påkrevd, og alle API-anrop uten den vil mislykkes.
Hvis du vil angi versjonen i en API-forespørsel via Python, inkluderer du nøkkel/verdi-paret i overskriftene for hver API-forespørsel. For eksempel: headers = {'X-Version': '2026-01-01'}
For øyeblikket kan du angi enten 2026-01-01 eller 2022-01-01.
Siden det er mange endringer i versjon 2026-01-01, er det viktig å sikre at både X-Version-overskriften er angitt for den aktuelle versjonen, og at API-endepunktets URL-bane og parametere samsvarer med den nødvendige strukturen for den aktuelle versjonen. I tillegg er det viktig å forstå svarformatet for API-kallet og eventuelle forskjeller i dette formatet mellom ulike versjoner.
Eksempler
Eksempel på GET-forespørsel
Her er et eksempel på bruk av en GET-forespørsel i endepunktet Hent en liste over regneark for både 2026-01-01- og 2022-01-01-versjonene (disse eksemplene inkluderer bærertokenet som tokenvariabel for obfuskeringsformål i denne artikkelen).
2026-01-01 versjon
# 2026-01-01 versjon # legg merke til X-Version-overskriften og URL-adressen til forespørselen 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 versjon
# 2022-01-01 versjon # legg merke til X-Version-overskriften og URL-adressen til forespørselen headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } resp = requests.get( 'https://api.app.wdesk.com/platform/v1/spreadsheets', headers = headers, ) Eksempel på PATCH-forespørsel
Nedenfor er et eksempel på bruk av en PATCH-forespørsel i endepunktet Delvis oppdatering av en enkelt seksjon for både 2026-01-01- og 2022-01-01-versjonene (disse eksemplene inkluderer bærertokenet som tokenvariabel i denne artikkelen for tilsløringsformål).
2026-01-01 versjon
# 2026-01-01 versjon # legg merke til X-Version header og forespørsler URL headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization':token, 'X-Version': '2026-01-01', } patch_op = [ { { "op": "replace", "path": "/name", "value": "My New Section Name" } ] resp = requests.patch ( https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) 2022-01-01 versjon
# 2022-01-01 versjon # legg merke til X-Version-overskriften og URL-forespørselen headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } patch_op = [ { { "op": "replace", "path": "/name", "value": "Mitt nye seksjonsnavn" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) Tips: I tillegg til å sikre at URL-banen og parameterstrukturen samsvarer med den aktuelle API-versjonen, må du sjekke dokumentasjonen for detaljer om de tilgjengelige parameteralternativene.
I eksemplet Delvis oppdatering av en enkelt seksjon ovenfor er det for eksempel tre tilgjengelige banealternativer i 2022-01-01-versjonen (/name , /index , /parent ), men i 2026-01-01-versjonen er det over tretti tilgjengelige banealternativer.
Beste praksis for skripting og API-versjonering
Den spesifikke API-versjonen du trenger, kan avhenge av statusen til aktive skript og applikasjoner, tidsfrister for oppgradering til den nye API-versjonen eller andre faktorer, men nedenfor følger noen beste fremgangsmåter knyttet til skripting og API-versjonering.
Angi alltid API-versjonen
Stol aldri på en API-leverandørs standardversjon. Angi versjonen eksplisitt i hvert API-kall. Ved å spesifisere versjonen eksplisitt har du kontroll over hvilken versjon skriptet eller programmet kjører.
Sentraliser versjonskonstanten
Definer API-versjonen som en enkelt konstant eller konfigurasjonsvariabel øverst i skriptet eller i en separat konfigurasjonsfil. Dette effektiviserer feilsøkingen og forbedrer vedlikeholdsarbeidet. Eksempel:
# config.py eller øverst i hovedskriptet API_VERSION = '2026-01-01' # i et request-anrop headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, ) Unngå å blande API-versjoner
Ikke prøv å blande API-versjoner i ett og samme skript eller program. Alle API-kall i et enkelt skript eller en enkelt applikasjon skal referere til den samme Workiva API-versjonen (f.eks. skal alle API-kall bruke versjonen "2026-01-01"). Blanding av versjoner kompliserer feilsøking, forespørselsskjemaer og svarformater, noe som gjør skriptets oppførsel uforutsigbar og vedlikeholdet mer komplisert.
Isoler API-interaksjonslogikk
Opprett en egen modul eller et sett med funksjoner (ofte kalt en "wrapper" eller "klient") som håndterer all kommunikasjon med det eksterne API-et. Dette mønsteret skiller "forretningslogikken" i skriptet ditt fra "API-kommunikasjonslogikken" Hvis API-et endres (f.eks. hvis endepunktets URL-adresse eller strukturen for forespørsel/svar endres i en ny API-versjon), er det bare omslagsfunksjonene som må oppdateres, ikke hele skriptet(ene).
Håndter utdaterte endepunkter og parametere på en god måte
Når du migrerer fra en gammel API-versjon til en ny, må du regne med at endepunkter og parametere kan bli omdøpt eller fjernet. Sørg for at skriptet ditt inneholder robust feilhåndtering og -logging, da dette støtter beste praksis for skriptutvikling og øker sannsynligheten for at versjonsrelaterte feil fanges opp og logges.
For mer informasjon om beste praksis for skripting, se Workiva Scripting: Beste praksis for utvikling artikkel.
Overvåk og planlegg for utfasing
Workiva går over til å tilby to lanseringsvinduer per år for nye hovedversjoner; vår og høst. Dersom det ikke er noen vesentlige endringer når det nærmer seg en utgivelsesdato og releasekandidaten for den aktuelle perioden er tom, vil Workiva ikke publisere en ny versjon av API-et på det tidspunktet.
Vi anbefaler at du aktivt følger med på nettstedet Workiva API Developer Hub, abonnerer på Workiva Release Notes, og følger de publiserte tidsplanene for utgivelser og utfasing. Skript som bruker en utdatert API-versjon, vil til slutt gå i stykker. Når du kjenner til utløpsdatoen for en API-versjon, kan du planlegge det nødvendige oppgraderingsarbeidet før utløpsdatoen.
Migrering og validering av skript
For å sikre en sømløs migrering av API-versjoner bør du etablere en parallell teststrategi: Kopier det eksisterende produksjonsskriptet, modifiser kun kopien til den nye API-versjonen (inkludert eventuelle nødvendige endringer i overskrifter, URL-bane og/eller forespørsels-/responsstruktur), og test deretter både det gamle og det nye skriptet for å sammenligne og verifisere funksjonalitet og utdata.
Ved å kjøre dem side om side i et kontrollert miljø kan du bruke det stabile, eldre skriptet som standard for å overvåke og verifisere at funksjonaliteten og resultatet som det nye skriptet produserer, er identisk før du går helt over til den nye versjonen og fjerner den gamle versjonen.