Controle de versão da API na Workiva
O controle de versão da API (Application Programming Interface, Interface de Programação de Aplicativos) é a prática crítica de atribuir identificadores exclusivos a diferentes iteradores do design de uma API para gerenciar e comunicar alterações de forma eficaz. Seu objetivo primário é manter a compatibilidade com versões anteriores, garantindo que os scripts e aplicativos que dependem de uma versão mais antiga não sejam interrompidos quando uma nova versão da API for lançada. Essa estabilidade permite que os provedores de API introduzam atualizações importantes, correções de bugs e novos recursos sem interromper os usuários existentes, concedendo aos consumidores o tempo e o controle necessários para migrar seus sistemas quando estiverem prontos. Em última análise, o controle de versão adequado da API promove um ecossistema de desenvolvimento confiável, dimensionável e profissional.
Lançamento da versão da API 2026-01-01
Em janeiro de 2026, a Workiva lançará uma nova versão da API, 2026-01-01. Essa nova versão apresenta melhorias significativas em várias áreas, incluindo consistência aprimorada, novas funções e eliminação de recursos legados. Os benefícios da atualização para a versão 2026-01-01 incluem a compatibilidade contínua com os recursos mais recentes da Workiva Platform, segurança aprimorada, desempenho melhorado e a capacidade de aproveitar novos recursos.
Para obter mais informações sobre a nova versão da API, consulte Workiva API 2026-01-01 Upgrade Guide.
Descontinuação da versão 2022-01-01 da API
Com o lançamento da versão 2026-01-01, a versão 2022-01-01 mais antiga entrará em sua fase de depreciação. O suporte para essa versão mais antiga continuará até seu encerramento em janeiro de 2029, e o suporte para os endpoints do Prototype 2022-01-01 será encerrado em janeiro de 2027.
Nota: A maioria dos endpoints Prototype na versão 2022-01-01 foi promovida para General Availability (GA) na versão 2026-01-01.
| Versão | Status | Tipo de endpoint | Data do pôr do sol |
|---|---|---|---|
| 2026-01-01 | Disponibilidade geral (GA) | Tudo | N/A (atual) |
| 2022-01-01 | Obsoleto | Protótipo | Janeiro de 2027 |
| 2022-01-01 | Obsoleto | GA | Janeiro de 2029 |
Comparação de versões da API
Quando uma nova versão é lançada, a documentação da API para essa versão no Workiva Developers Hub inclui uma seção Changelog que inclui documentação detalhada sobre as alterações da API nessa versão. A versão 2026-01-01 terá uma seção 2026-01-01 Upgrade Guide com um passo a passo completo das alterações nessa versão.
Além disso, há muitas ferramentas de fonte aberta disponíveis para que você execute uma comparação em duas versões diferentes da API. Com esses tipos de ferramentas, você pode fazer comparações rápidas e detalhadas das alterações de versão. A ferramenta de fonte aberta oasdiff tem uma calculadora de diferenças baseada na Web que permite que você carregue dois arquivos de configuração de versão de API (oas.yaml) e execute uma comparação para alterações de quebra, registros de mudanças ou uma diferença bruta. Você pode obter saída de resultados em texto, yaml, json, html e markdown.
Faça referência a uma versão específica da API
As APIs da Workiva utilizam o cabeçalho X-Version para especificar qual versão da API você deve usar. Se o cabeçalho X-Version não for passado, a versão padrão será a versão depreciada 2022-01-01.
Nota: Após janeiro de 2029, o cabeçalho X-Version será obrigatório e todas as chamadas de API sem ele falharão.
Para especificar a versão em uma solicitação de API via Python, inclua o par chave/valor nos cabeçalhos de cada solicitação de API. Por exemplo: cabeçalhos = {'X-Version': '2026-01-01'}
Atualmente, você pode especificar 2026-01-01 ou 2022-01-01.
Como há muitas alterações significativas na versão 2026-01-01, é fundamental garantir que o cabeçalho X-Version esteja definido para a versão aplicável e que o caminho e os parâmetros do URL do ponto de extremidade da API correspondam à estrutura necessária dessa versão. Além disso, é importante que você entenda o formato de resposta da chamada à API e as possíveis diferenças desse formato entre as versões.
Exemplos
Exemplo de solicitação GET
Aqui você encontra um exemplo de uso de uma solicitação GET no ponto de extremidade Retrieve a List of Spreadsheets para as versões 2026-01-01 e 2022-01-01 (esses exemplos incluem o token do portador como variável de token para fins de ofuscação neste artigo).
Versão 2026-01-01
# versão 2026-01-01 # note o cabeçalho X-Version e o URL das solicitações headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2026-01-01', } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, )Versão 2022-01-01
# Versão 2022-01-01 # note o cabeçalho X-Version e o URL da solicitação headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } resp = requests.get( 'https://api.app.wdesk.com/platform/v1/spreadsheets', headers = headers, ) Exemplo de solicitação de PATCH
Abaixo está um exemplo de uso de uma solicitação PATCH no ponto de extremidade Atualizar parcialmente uma única seção para as versões 2026-01-01 e 2022-01-01 (esses exemplos incluem o token do portador como a variável do token neste artigo para fins de ofuscação).
Versão 2026-01-01
# versão 2026-01-01 # note o cabeçalho X-Version e o URL das solicitações 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, ) Versão 2022-01-01
# versão 2022-01-01 # note o cabeçalho X-Version e o URL das solicitações headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } patch_op = [ { "op": "replace", "path": "/name", "valor": "My New Section Name" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, ) Dica: Além de garantir que o caminho do URL e a estrutura dos parâmetros correspondam à versão aplicável da API, verifique a documentação para obter detalhes sobre as opções de parâmetros disponíveis.
Por exemplo, no exemplo de atualização parcial de uma única seção acima, na versão 2022-01-01 há três opções de caminho disponíveis ( /nome , /index , /parent ), mas na versão 2026-01-01 há mais de trinta opções de caminho disponíveis.
Melhores práticas para criação de scripts e controle de versão da API
Embora a versão específica da API que você precisa possa depender do status dos scripts e aplicativos ativos, dos prazos de atualização para a nova versão da API ou de outros fatores, veja a seguir algumas das melhores práticas relacionadas a scripts e versões da API.
Sempre especifique a versão da API
Nunca confie na versão padrão de um provedor de API. Especifique explicitamente a versão em cada chamada de API. Ao especificar explicitamente a versão, você controla a versão que o script ou o aplicativo executa.
Centralize a constante de versão
Defina a versão da API como uma única constante ou variável de configuração facilmente localizável na parte superior do script ou em um arquivo de configuração separado. Isso simplifica de forma confiável a solução de problemas e melhora a capacidade de manutenção. Exemplo:
# config.py ou na parte superior do script principal API_VERSION = '2026-01-01' # em uma chamada de solicitações headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, ) Evite misturar versões de API
Não tente misturar versões de API em um único script ou aplicativo. Todas as chamadas de API em um único script ou aplicativo devem fazer referência à mesma versão da API da Workiva (por exemplo, todas as chamadas de API devem usar a versão "2026-01-01"). A mistura de versões complica a depuração, os esquemas solicitantes e os formatos de resposta, tornando o comportamento do script imprevisível e a manutenção mais complicada.
Isolar a lógica de interação da API
Crie um módulo dedicado ou um conjunto de funções (geralmente chamado de "wrapper" ou "cliente") que lide com toda a comunicação com a API externa. Esse padrão separa a "lógica comercial" do seu script da "lógica de comunicação da API". Se a API for alterada (por exemplo, o URL do endpoint ou a estrutura solicitante/resposta for alterada em uma nova versão da API), somente as funções do wrapper precisarão ser atualizadas, e não os scripts inteiros.
Você pode lidar com parâmetros e pontos de extremidade obsoletos de forma adequada
Ao migrar de uma versão antiga da API para uma nova, você deve prever que os pontos de extremidade e os parâmetros poderão ser renomeados ou removidos. Certifique-se de que seu script inclua tratamento e registro de erros robustos, pois isso oferece suporte às melhores práticas para o desenvolvimento de scripts, além de aumentar a probabilidade de que erros relacionados à versão sejam detectados e registrados.
Para obter mais informações sobre as melhores práticas de script, consulte o artigo Workiva Scripting: Melhores práticas de desenvolvimento .
Monitore e planeje a depreciação
A Workiva está mudando para fornecer duas janelas de lançamento por ano para novas versões principais: primavera e outono. Caso não haja alterações significativas quando uma data de lançamento se aproximar e o candidato a lançamento para esse período estiver vazio, a Workiva não publicará uma nova versão da API nesse tempo.
Recomendamos que você acompanhe ativamente o site Workiva API do desenvolvedor, assine o site Workiva Release Notes e siga os cronogramas de lançamento e depreciação publicados. Os scripts que usam uma versão de API obsoleta acabarão sendo interrompidos. Conhecer a data de expiração (fim da vida útil) de uma versão da API permite que você programe o trabalho de atualização necessário antes da data de expiração.
Migração e validação de scripts
Para garantir a migração perfeita da versão da API, estabeleça uma estratégia de testes paralelos: copie o script de produção existente, altere apenas a cópia para que ela seja direcionada à nova versão da API (incluindo as alterações necessárias nos cabeçalhos, no caminho do URL e/ou na estrutura solicitante/resposta) e, em seguida, teste o script antigo e o novo para comparar e verificar a funcionalidade e a saída.
Ao executá-los lado a lado em um ambiente controlado, você pode usar o script mais antigo e estável como padrão para monitorar e verificar se a funcionalidade e o resultado produzidos pelo novo script são idênticos antes de mudar totalmente para a nova versão e descontinuar a versão antiga.