Versionado de API en Workiva
El versionado de la Interfaz de Programación de Aplicaciones (API) es la práctica fundamental de asignar identificadores únicos a las distintas iteraciones del diseño de una API para gestionar y comunicar los cambios con eficacia. Su objetivo principal es mantener la compatibilidad con versiones anteriores, garantizando que los scripts y las aplicaciones que dependen de una versión anterior no se rompan cuando se publique una nueva versión de la API. Esta estabilidad permite a los proveedores de API introducir actualizaciones importantes, correcciones de errores y nuevas funciones sin interrumpir a los usuarios existentes, concediendo a los consumidores el tiempo y el control necesarios para migrar sus sistemas cuando estén preparados. En última instancia, el correcto versionado de la API promueve un ecosistema de desarrollo fiable, escalable y profesional.
2026-01-01 Lanzamiento de la Versión de la API
En enero de 2026 Workiva lanzará una nueva versión de la API, 2026-01-01. Esta nueva versión introduce mejoras significativas en múltiples áreas, incluida una mayor coherencia, nuevas funciones y la eliminación de funciones heredadas. Las ventajas de actualizar a la versión 2026-01-01 incluyen la compatibilidad continuada con las últimas características de la Plataforma Workiva seguridad mejorada, rendimiento mejorado y la capacidad de aprovechar nuevas funciones.
Para obtener información adicional sobre la nueva versión de la API, consulta la Guía de actualización de la API Workiva 2026-01-01 .
Versión obsoleta de la API 2022-01-01
Con el lanzamiento de la versión 2026-01-01, la versión antigua 2022-01-01 entrará en su fase de caducidad. El soporte para esta versión antigua continuará hasta su desaparición en enero de 2029, y el soporte para los puntos finales del Prototipo 2022-01-01 finalizará en enero de 2027.
Nota: La mayoría de los puntos finales del Prototipo en la versión 2022-01-01 han sido promovidos a Disponibilidad General (GA) en la versión 2026-01-01.
| Versión | Estado | Tipo de punto final | Fecha de expiración |
|---|---|---|---|
| 2026-01-01 | Disponibilidad general (GA) | Todo | N/A (Actual) |
| 2022-01-01 | En desuso | Prototipo | Enero 2027 |
| 2022-01-01 | En desuso | GA | Enero de 2029 |
Comparación de Versiones de la API
Cuando se publica una nueva versión, la documentación de la API para esa versión en el Workiva Developers Hub incluye una sección de Registro de cambios que incluye documentación detallada sobre los cambios de la API en esa versión. La versión 2026-01-01 tendrá una sección 2026-01-01 Guía de actualización con un recorrido completo de los cambios en esa versión.
Además, hay muchas herramientas de código abierto disponibles para ejecutar una comparación en dos versiones diferentes de la API. Este tipo de herramientas permiten realizar comparaciones rápidas y detalladas de los cambios de versión. La herramienta de código abierto oasdiff tiene una calculadora de diferencias basada en la web que te permite subir dos archivos de configuración de versiones de la API (oas.yaml) y ejecutar una comparación de cambios de rotura, registros de cambios o diferencias sin procesar. Puede mostrar los resultados en texto, yaml, json, html y markdown.
Referencia a una versión específica de la API
Las API de Workiva aprovechan el encabezado X-Version para especificar qué versión de API utilizar. Si no se pasa la cabecera X-Version, la versión Predeterminada será la 2022-01-01.
Nota: Después de enero de 2029, el encabezado X-Version será obligatorio y todas las llamadas a la API sin él fallarán.
Para especificar la versión en una solicitud de API mediante Python, incluye el par clave/valor en los encabezados de cada solicitud de API. Por ejemplo: headers = {'X-Version': '2026-01-01'}
Actualmente puedes especificar 2026-01-01 o 2022-01-01.
Dado que hay muchos cambios de última hora en la versión 2026-01-01, es fundamental asegurarse de que tanto el encabezado X-Version está configurado para la versión aplicable como la ruta URL del punto final de la API y los parámetros coinciden con la estructura requerida de esa versión. Además, es importante comprender el formato de respuesta de la llamada a la API y cualquier posible diferencia de ese formato entre versiones.
Ejemplos
Ejemplo de Solicitud GET
Aquí tienes un ejemplo de uso de una solicitud GET en el punto final Recuperar una Lista de Hojas de Cálculo tanto para la versión 2026-01-01 como para la 2022-01-01 (estos ejemplos incluyen el token de portador como variable de token con fines de ofuscación en este artículo).
Versión 2026-01-01
# versión 2026-01-01 # ten en cuenta la cabecera X-Version y la URL de las solicitudes headers = { 'Accept': 'application/json', 'Autorización': token, 'X-Version': '2026-01-01', } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, )Versión 2022-01-01
# versión 2022-01-01 # observa la cabecera X-Version y la URL de la solicitud headers = { 'Accept': 'application/json', 'Autorización': token, 'X-Version': '2022-01-01', } resp = requests.get( 'https://api.app.wdesk.com/platform/v1/spreadsheets', headers = headers, ) Ejemplo de solicitud PATCH
A continuación se muestra un ejemplo de uso de una solicitud PATCH en el punto final Actualizar Parcialmente una Sección Única tanto para la versión 2026-01-01 como para la 2022-01-01 (estos ejemplos incluyen el token de portador como variable de token en este artículo con fines de ofuscación).
2026-01-01 versión
# versión 2026-01-01 # ten en cuenta la cabecera X-Version y la URL de las solicitudes headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Autorización':token, 'X-Version': '2026-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "My Nueva sección Name" } ] resp = requests.patch ( https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) 2022-01-01 versión
# versión 2022-01-01 # ten en cuenta la cabecera X-Version y la URL de las solicitudes headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Autorización': token, 'X-Version': '2022-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "My Nueva sección Name" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) Consejo: Además de asegurarte de que la ruta URL y la estructura de los parámetros coinciden con la versión de la API aplicable, asegúrate de consultar la documentación para obtener información detallada sobre las opciones de parámetros disponibles.
Por ejemplo, en el ejemplo anterior de Actualización parcial de una única sección, en la versión 2022-01-01 hay tres opciones de ruta disponibles ( /nombre , /índice , /padre ), pero en la versión 2026-01-01 hay más de treinta opciones de ruta disponibles.
Mejores prácticas para el script y el versionado de la API
Aunque la versión específica de la API que necesitas puede depender del estado de los scripts y aplicaciones activos, de los plazos de actualización a la nueva versión de la API o de otros factores, a continuación se exponen algunas de las mejores prácticas relacionadas con el versionado de scripts y de la API.
Especifica siempre la Versión de la API
No confíes nunca en la versión predeterminada de un proveedor de API. Especifica explícitamente la versión en cada llamada a la API. Al especificar explícitamente la versión tienes el control de qué versión ejecuta el script o la aplicación.
Centralizar la Constante de Versión
Define la versión de la API como una única constante o variable de configuración fácilmente localizable en la parte superior de tu script o en un archivo de configuración independiente. Esto agiliza de forma fiable la resolución de problemas y mejora la capacidad de mantenimiento. Ejemplo:
# config.py o en la parte superior del script principal API_VERSION = '2026-01-01' # en una llamada a requests headers = { 'Accept': 'application/json', 'Autorización': token, 'X-Version': API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, ) Evita mezclar versiones de la API
No intentes mezclar versiones de API dentro de un mismo script o aplicación. Todas las llamadas a la API dentro de un mismo script o aplicación deben hacer referencia a la misma versión de la API Workiva (por ejemplo, todas las llamadas a la API deben utilizar la versión "2026-01-01"). Mezclar versiones complica la depuración, los esquemas de solicitud y los formatos de respuesta, haciendo que el comportamiento del script sea impredecible y el mantenimiento más complicado.
Aislar la lógica de interacción con la API
Establece un módulo dedicado o un conjunto de funciones (a menudo llamado "envoltorio" o "cliente") que gestione toda la comunicación con la API externa. Este patrón separa la "lógica de negocio" de tu script de la "lógica de comunicación de la API". Si la API cambia (por ejemplo, la URL del punto final o la estructura de solicitud/respuesta cambia en una nueva versión de la API), sólo hay que actualizar las funciones de envoltorio, no todo el script(s).
Gestiona con elegancia los puntos finales y parámetros obsoletos
Cuando migres de una versión antigua de la API a una nueva, ten en cuenta que los puntos finales y los parámetros pueden cambiar de nombre o eliminarse. Asegúrate de que tu script incluya una gestión y un registro de errores sólidos, ya que esto es compatible con las mejores prácticas de desarrollo de scripts, además de aumentar la probabilidad de que se detecten y registren los errores relacionados con las versiones.
Para obtener información adicional sobre las mejores prácticas de scripting, consulta el artículo Workiva Scripting: Mejores prácticas de desarrollo .
Supervisar y planificar la eliminación de versiones
Workiva está pasando a proporcionar dos ventanas de publicación al año para las nuevas versiones principales; Primavera y Otoño. En caso de que no haya cambios de última hora cuando se acerque una fecha de lanzamiento y la versión candidata para ese periodo esté vacía, Workiva no publicará una nueva versión de la API en ese momento.
Te recomendamos que realices un seguimiento activo del sitio web Workiva API Developer Hub, te suscribas a Workiva Release Notas, y sigas los calendarios publicados de versiones y versiones obsoletas. Los scripts que utilicen una versión obsoleta de la API acabarán rompiéndose. Conocer la fecha de expiración (fin de la vida útil) de una versión de la API te permite programar el trabajo de actualización necesario antes de la fecha de expiración.
Migración y validación de scripts
Para garantizar una migración fluida de la versión de la API, establece una estrategia de prueba paralela: copia el script de producción existente, modifica sólo la copia para orientarla a la nueva versión de la API (incluidos los cambios necesarios en las cabeceras, la ruta de la URL y/o la estructura de solicitud/respuesta) y, a continuación, prueba tanto el script antiguo como el nuevo para comparar y verificar la funcionalidad y el resultado.
Ejecutándolos uno al lado del otro en un entorno controlado, puedes utilizar el script estable más antiguo como estándar para controlar y verificar que la funcionalidad y el resultado producidos por el nuevo script son idénticos antes de pasar completamente a la nueva versión y depreciar la versión antigua.