A maioria dos aplicativos é escrita usando alguma forma de um SDK cliente ou possivelmente 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 vai continuar funcionando mesmo que o Looker faça 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 e, portanto, aos aplicativos.
À medida que adicionamos mais recursos e capacidades ao Looker, também atualizamos a API REST do Looker para acessar ou gerenciar esses novos recursos. Para cada versão do Looker, adicionamos novas funções, parâmetros e propriedades de tipo de resposta da API à versão atual da API Looker. Na maioria dos casos, as adições à API não são mudanças interruptivas. Por isso, podemos manter a versão atual da API sem afetar o código do aplicativo 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 alterações na API que interrompam o código do aplicativo existente, agrupamos essas alterações interruptivas 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 você escolher quando fazer upgrade para a nova versão da API. O código criado para chamar o endpoint antigo continuará a fazer isso. O novo código precisa chamar a nova versão do endpoint no nível da versão mais recente da API.
Uma exceção é o caso de 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.
Quando precisamos desativar um recurso, uma função ou uma propriedade para melhorar a implementação ou a solução, normalmente deixamos a API atual como ela está, mas marcamos os endpoints de API associados como "descontinuados" para indicar que você precisa mudar do endpoint no código do aplicativo.
Mudanças interruptivas e aditivas na API
Uma alteração interruptiva é algo que exclui ou renomeia um artefato atual de um endpoint de API. Isso pode incluir:
- Como alterar 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
Por outro lado, uma mudança aditiva pode ser feita em endpoints estáveis. Eles podem incluir:
- Novos parâmetros opcionais
- Novas propriedades nas respostas. Não consideramos isso uma falha 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 Looker precisar de uma mudança significativa para avançar com uma nova arquitetura ou funcionalidade, a mudança geralmente será adicionada a um novo endpoint e agrupada em uma nova versão da API para que o endpoint atual da API permaneça inalterado.
Sinalizações 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 lança mudanças interruptivas para 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 Descontinuado:
- 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.
- 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, os códigos que ainda o utilizam serão corrompidos. Na maioria dos casos, um endpoint descontinuado será 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 que não estã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 no código do aplicativo os nomes atualizados de funções, valores e propriedades.
- 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
Para 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 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 seu aplicativo for escrito em uma linguagem dinâmica com tipos flexíveis (como JavaScript, Ruby e Python), pode ser mais difícil localizar as partes do aplicativo que serão afetadas por alterações interruptivas em uma nova versão da API. Esses tipos de linguagens podem exigir testes de unidade de tempo de execução para encontrar problemas relacionados a alterações nos tipos.
Em todos os casos, a prática recomendada é ter testes de unidade que executem o código do aplicativo, incluindo chamadas à API Looker (não chamadas simuladas).