A maioria dos aplicativos é gravada usando algum tipo de SDK de cliente ou talvez um URL de API. Os URLs do SDK do cliente e da API estão vinculados a uma versão específica da API Looker. Seu aplicativo continuará funcionando mesmo quando o Looker fizer mudanças nas novas versões da API. O aplicativo não será afetado por mudanças em outras versões da API até que você escolha fazer upgrade do SDK do cliente ou modificar o URL da API para usar a nova versão da API Looker.
Como o Looker faz mudanças na API
A API Looker foi projetada para oferecer estabilidade aos endpoints da API Looker e, portanto, aos seus aplicativos.
À medida que adicionamos mais recursos e funcionalidades ao Looker, também atualizamos a API REST do Looker para acessar ou gerenciar esses novos recursos. Em cada versão do Looker, adicionamos novas funções, parâmetros e propriedades de tipo de resposta da API à versão atual da API do Looker. Na maioria dos casos, as adições à API não são mudanças interruptivas, então podemos manter a versão atual da API sem afetar o código do aplicativo que foi criado com base nela. O código do seu aplicativo pode não conhecer novas funções, parâmetros ou recursos que aparecem nas versões subsequentes do Looker.
Para mudanças na API que interromperiam o código do aplicativo atual, agrupamos essas mudanças em uma nova versão da API. Isso significa que a versão antiga da API vai continuar funcionando da mesma forma, enquanto a nova versão da API é executada ao lado dela com as mudanças e atualizações. Várias versões da API podem existir lado a lado em uma única instância do Looker para que você possa escolher quando fazer upgrade para a nova versão da API. O código criado para chamar o endpoint antigo continuará a chamar o endpoint antigo. O novo código precisa chamar a nova versão do endpoint no nível de versão mais recente da API.
Uma exceção a isso são os problemas de segurança críticos. Se descobrirmos um problema de segurança grave relacionado a uma parte específica da API, faremos o necessário para mitigá-lo o mais rápido possível, o que pode incluir a desativação da funcionalidade vulnerável até que uma solução adequada esteja disponível.
Se precisarmos descontinuar um recurso, função ou propriedade para dar lugar a uma implementação ou solução melhor, normalmente deixamos a API atual como está, mas marcamos os endpoints associados como "descontinuado" para indicar que você precisa se afastar do endpoint no código do aplicativo.
Mudanças interruptivas e aditivas na API
Uma mudança interruptiva é algo que exclui ou renomeia um artefato de um endpoint de API. Isso pode incluir:
- Como mudar ou excluir um nome ou tipo de parâmetro
- Adicionar um novo parâmetro obrigatório
- Como mudar o URL base
- Como mudar ou excluir uma propriedade em uma resposta
Uma mudança aditiva, por outro lado, pode ser feita em endpoints estáveis. Eles podem incluir:
- Novos parâmetros opcionais
- Novas propriedades nas respostas (não consideramos isso uma mudança significativa porque presumimos que seu código vai ignorar propriedades desconhecidas nas respostas, o que é uma prática comum na comunidade da API REST)
Se um endpoint estável da API do Looker precisar de uma mudança significativa para avançar com uma nova arquitetura ou funcionalidade, a mudança geralmente é adicionada a um novo endpoint e agrupada em uma nova versão da API para que o endpoint de API atual permaneça inalterado.
Flags para endpoints de API
A maioria dos endpoints de API é considerada estável, o que significa que eles não devem mudar. O Looker não vai lançar mudanças importantes em endpoints estáveis, exceto em casos extremos, como para corrigir um problema de segurança.
Outros endpoints de API podem ser sinalizados como Beta ou Obsoleto:
- Os endpoints Beta estão em desenvolvimento ativo e podem mudar no futuro. Eles não são protegidos contra mudanças que quebram. Ao usar endpoints Beta, considere se uma mudança na API Looker seria particularmente perturbadora para seu app ou ciclo de desenvolvimento. Leia as notas da versão do Looker se você planeja usar um endpoint Beta para saber de todas as mudanças.
- Os endpoints descontinuados são endpoints que ainda têm suporte e podem ser usados no momento, mas serão excluídos em uma versão futura. O código antigo que usa um endpoint descontinuado precisa ser atualizado para deixar de usar o endpoint descontinuado. Quando uma versão futura do Looker remover o suporte a esse endpoint, qualquer código que ainda o esteja usando será interrompido. Na maioria dos casos, um endpoint descontinuado é substituído por uma funcionalidade aprimorada. Se você descobrir que o aplicativo está usando uma função ou propriedade descontinuada, refatore o código para substituir o elemento descontinuado assim que possível.
Os endpoints Beta e descontinuados são marcados como tal no API Explorer e na Referência da API 4.0. Os endpoints não marcados são considerados estáveis.
Como migrar para uma nova versão da API
Ao escolher fazer upgrade do SDK do cliente ou do URL da API para uma nova versão, você precisa analisar o código do aplicativo para saber se está dependendo de algo que mudou com a nova versão da API. Faça o seguinte:
- Pesquise a função, o valor e os nomes de propriedade atualizados no código do aplicativo.
- Verifique se o código do aplicativo oferece suporte a mudanças de tipos (como de número inteiro para string).
- Faça uma auditoria do código (consulte a seção Auditar seu código).
Como auditar seu código
Em alguns idiomas, as mudanças de interrupção na API podem ser descobertas no momento do build como erros de compilação:
- Se o aplicativo for escrito em uma linguagem compilada e fortemente tipada, as mudanças estruturais nos tipos de parâmetro ou de resposta em uma nova versão da API que estão em conflito com o código atual precisam ser facilmente aparentes, graças à verificação de tipo de compilação e às mensagens de erro do compilador.
- Se o aplicativo for escrito em uma linguagem dinâmica com tipificação fraca (como JavaScript, Ruby e Python), pode ser mais difícil localizar as partes do aplicativo que serão afetadas por mudanças de interrupção em uma nova versão da API. Esses tipos de linguagem podem exigir testes de unidade de execução para encontrar problemas relacionados a mudanças nos tipos.
Em todos os casos, a prática recomendada é ter testes de unidade que exercitem o código do aplicativo, incluindo chamadas para a API Looker (não chamadas simuladas).