Il versionamento delle API in Workiva
Il versioning delle interfacce di programmazione delle applicazioni (API) è la pratica fondamentale di assegnare identificatori unici alle diverse iterazioni del design di un'API per gestire e comunicare efficacemente le modifiche. Il suo scopo principale è quello di mantenere la retrocompatibilità, assicurando che gli script e le applicazioni che si basano su una versione precedente non si rompano quando viene rilasciata una nuova versione dell'API. Questa stabilità consente ai fornitori di API di introdurre aggiornamenti importanti, correzioni di bug e nuove funzionalità senza interrompere gli utenti esistenti, garantendo agli utenti il tempo e il controllo necessari per migrare i loro sistemi quando sono pronti. In definitiva, un corretto versioning delle API promuove un ecosistema di sviluppo affidabile, scalabile e professionale.
2026-01-01 Rilascio della versione API
Nel gennaio 2026 Workiva rilascerà una nuova versione dell'API, 2026-01-01. Questa nuova versione introduce miglioramenti significativi in diverse aree, tra cui una maggiore coerenza, nuove funzionalità e l'eliminazione di quelle già esistenti. I vantaggi dell'aggiornamento alla versione 2026-01-01 includono la continua compatibilità con le ultime caratteristiche della piattaforma Workiva, una maggiore sicurezza, migliori prestazioni e la possibilità di sfruttare nuove funzionalità.
Per ulteriori informazioni sulla nuova versione dell'API, consulta la Guida all'aggiornamento di Workiva API 2026-01-01.
Deprecazione della versione API 2022-01-01
Con il rilascio della versione 2026-01-01, la versione precedente 2022-01-01 entrerà nella fase di deprezzamento. Il supporto per questa versione precedente continuerà fino al suo tramonto nel gennaio 2029, mentre il supporto per gli endpoint del Prototipo 2022-01-01 terminerà nel gennaio 2027.
Nota: La maggior parte degli endpoint Prototype della versione 2022-01-01 sono stati promossi a General Availability (GA) nella versione 2026-01-01.
| Versione | Stato | Tipo di endpoint | Data del tramonto |
|---|---|---|---|
| 2026-01-01 | Disponibilità generale (GA) | Tutte | N/A (Attuale) |
| 2022-01-01 | Obsoleto | Prototipo | Gennaio 2027 |
| 2022-01-01 | Obsoleto | GA | Gennaio 2029 |
Confronto tra le versioni delle API
Quando viene rilasciata una nuova versione, la documentazione API per quella versione sul Workiva Developers Hub include una sezione Changelog che contiene una documentazione dettagliata sulle modifiche API apportate a quella versione. La versione 2026-01-01 avrà una sezione 2026-01-01 Upgrade Guide con una descrizione completa delle modifiche apportate alla versione.
Inoltre, sono disponibili molti strumenti open source per eseguire un confronto tra due diverse versioni di API. Questo tipo di strumenti consente di confrontare rapidamente e in modo dettagliato i cambiamenti di versione. Lo strumento open source oasdiff ha un calcolatore di differenze basato sul web che ti permette di caricare due file di configurazione della versione dell'API (oas.yaml) e di eseguire un confronto per individuare le modifiche di rottura, i changelog o una differenza grezza. Può produrre risultati in testo, yaml, json, html e markdown.
Riferimento a una versione specifica dell'API
Le API di Workiva utilizzano l'intestazione X-Version per specificare la versione API da utilizzare. Se l'intestazione X-Version non viene passata, la versione predefinita è la versione deprecata 2022-01-01.
Nota: Dopo il gennaio 2029 l'intestazione X-Version sarà obbligatoria e tutte le chiamate API senza di essa falliranno.
Per specificare la versione in una richiesta API tramite Python, includi la coppia chiave/valore nelle intestazioni di ogni richiesta API. Ad esempio: headers = {'X-Version': '2026-01-01'}
Attualmente puoi specificare 2026-01-01 o 2022-01-01.
Dato che la versione 2026-01-01 contiene molte modifiche, è fondamentale assicurarsi che l'intestazione X-Version sia impostata per la versione in questione e che il percorso e i parametri dell'URL dell'endpoint API corrispondano alla struttura richiesta per quella versione. Inoltre, è importante capire il formato di risposta della chiamata API e le eventuali differenze tra le varie versioni.
Esempi
Esempio di richiesta GET
Ecco un esempio di utilizzo di una richiesta GET nell'endpoint Recupera un elenco di fogli di calcolo sia per la versione 2026-01-01 che per la versione 2022-01-01 (questi esempi includono il token del portatore come variabile token ai fini dell'offuscamento in questo articolo).
Versione 2026-01-01
# versione 2026-01-01 # nota l'intestazione X-Version e l'URL della richiesta headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2026-01-01', } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, )Versione 2022-01-01
# versione 2022-01-01 # nota l'intestazione X-Version e l'URL della richiesta headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } resp = requests.get( 'https://api.app.wdesk.com/platform/v1/spreadsheets', headers = headers, ) Esempio di richiesta PATCH
Di seguito è riportato un esempio di utilizzo di una richiesta PATCH nell'endpoint Partially Update a Single Section sia per la versione 2026-01-01 che per la versione 2022-01-01 (questi esempi includono il token del portatore come variabile token in questo articolo a scopo di offuscamento).
Versione 2026-01-01
# versione 2026-01-01 # nota l'intestazione X-Version e l'URL delle richieste headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization':token, 'X-Version': '2026-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "Il mio nuovo nome di sezione" } ] resp = requests.patch ( https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) Versione 2022-01-01
# versione 2022-01-01 # nota l'intestazione X-Version e l'URL delle richieste headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "My New Section Name" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) Suggerimento: Oltre a verificare che il percorso dell'URL e la struttura dei parametri corrispondano alla versione dell'API applicabile, assicurati di controllare la documentazione per conoscere i dettagli sulle opzioni dei parametri disponibili.
Ad esempio, nell'esempio precedente di aggiornamento parziale di una singola sezione, nella versione 2022-01-01 ci sono tre opzioni di percorso disponibili ( /nome , /indice , /parente ), ma nella versione 2026-01-01 ci sono oltre trenta opzioni di percorso disponibili.
Migliori pratiche per lo scripting e il versionamento delle API
Sebbene la versione specifica dell'API richiesta possa dipendere dallo stato degli script e delle applicazioni attive, dalle tempistiche di aggiornamento alla nuova versione dell'API o da altri fattori, di seguito sono riportate alcune best practice relative allo scripting e al versioning dell'API.
Specifica sempre la versione dell'API
Non affidarti mai alla versione predefinita di un fornitore di API. Specifica esplicitamente la versione in ogni chiamata API. Specificando esplicitamente la versione hai il controllo di quale versione viene eseguita dallo script o dall'applicazione.
Centralizzare la costante di versione
Definisci la versione dell'API come un'unica costante o variabile di configurazione facilmente individuabile all'inizio del tuo script o in un file di configurazione separato. Questo semplifica in modo affidabile la risoluzione dei problemi e migliora la manutenibilità. Esempio:
# config.py o all'inizio dello script principale API_VERSION = '2026-01-01' # in una chiamata a requests headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, ) Evitare di mischiare le versioni delle API
Non cercare di mescolare le versioni delle API all'interno di un singolo script o applicazione. Tutte le chiamate API all'interno di un singolo script o applicazione devono fare riferimento alla stessa versione dell'API di Workiva (ad esempio, tutte le chiamate API devono utilizzare la versione "2026-01-01"). Mescolare le versioni complica il debug, gli schemi di richiesta e i formati di risposta, rendendo il comportamento dello script imprevedibile e la manutenzione più complicata.
Isolare la logica di interazione con le API
Crea un modulo o un insieme di funzioni dedicato (spesso chiamato "wrapper" o "client") che gestisca tutte le comunicazioni con l'API esterna. Questo schema separa la "logica aziendale" del tuo script dalla "logica di comunicazione API". Se l'API cambia (ad esempio, l'URL dell'endpoint o la struttura della richiesta/risposta cambiano in una nuova versione dell'API), è necessario aggiornare solo le funzioni wrapper, non l'intero script.
Gestire con grazia gli endpoint e i parametri deprecati
Durante la migrazione da una vecchia versione dell'API a una nuova, devi prevedere che gli endpoint e i parametri possano essere rinominati o rimossi. Assicurati che il tuo script includa una solida gestione e registrazione degli errori, in quanto ciò supporta le migliori pratiche di sviluppo dello scripting e aumenta la probabilità che gli errori relativi alla versione vengano individuati e registrati.
Per ulteriori informazioni sulle migliori pratiche di scripting, consulta l'articolo Workiva Scripting: Development Best Practices .
Controlla e pianifica la deprecazione
Workiva sta passando a due finestre di rilascio all'anno per le nuove versioni principali: primavera e autunno. Nel caso in cui non ci siano cambiamenti sostanziali all'approssimarsi di una data di rilascio e la release candidate per quel periodo sia vuota, Workiva non pubblicherà una nuova versione dell'API in quel momento.
Ti consigliamo di seguire attivamente il sito web Workiva API Developer Hub, di abbonarti a Workiva Release Notes e di seguire le scadenze di rilascio e deprezzamento pubblicate. Gli script che utilizzano una versione API deprecata finiranno per rompersi. Conoscere la data di scadenza di una versione dell'API ti permette di programmare gli aggiornamenti necessari prima della data di scadenza.
Migrazione e convalida degli script
Per garantire una migrazione senza soluzione di continuità della versione dell'API, stabilisci una strategia di test parallela: copia lo script di produzione esistente, modifica solo la copia per puntare alla nuova versione dell'API (comprese le modifiche necessarie alle intestazioni, al percorso dell'URL e/o alla struttura delle richieste/risposte) e poi testa sia il vecchio che il nuovo script per confrontare e verificare la funzionalità e l'output.
Eseguendoli fianco a fianco in un ambiente controllato, puoi utilizzare lo script stabile più vecchio come standard per monitorare e verificare che la funzionalità e i risultati prodotti dal nuovo script siano identici prima di passare completamente alla nuova versione e deprecare la vecchia.