A maioria dos aplicativos é escrita usando alguma forma de SDK do cliente ou, possivelmente, um URL de API. O SDK do cliente e os URLs da API estão vinculados a uma versão específica da API Looker. Seu aplicativo vai continuar funcionando mesmo quando o Looker fizer mudanças nas novas versões da API. Seu aplicativo não será afetado por mudanças em outras versões da API até que você faça upgrade do SDK do cliente (ou modifique 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. 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. Assim, podemos manter a versão atual da API sem afetar o código do aplicativo criado com ela. O código do aplicativo atual pode simplesmente não conhecer novas funções, parâmetros ou recursos que aparecem em versões posteriores do Looker.
Para mudanças na API que interromperiam o código do aplicativo atual, agrupamos essas mudanças interruptivas em uma nova versão da API. Isso significa que a versão antiga da API vai continuar funcionando da mesma forma que antes, enquanto uma nova versão da API é executada ao lado dela com as mudanças e atualizações. Várias versões da API podem coexistir 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 atual criado para chamar o endpoint antigo vai continuar fazendo 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 a isso é para problemas críticos de segurança. Se descobrirmos um problema de segurança grave relacionado a uma parte específica da API, faremos o que for necessário para mitigar esse problema 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 desativar um recurso, uma função ou uma propriedade para abrir caminho para uma implementação ou solução melhor, normalmente deixamos a API atual como está, mas marcamos os endpoints associados como "descontinuados" para indicar que você precisa migrar 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 existente de um endpoint de API. Isso pode incluir:
- Mudar ou excluir um nome ou tipo de parâmetro
- Adicionar um novo parâmetro obrigatório
- Como mudar o URL base
- Mudar ou excluir uma propriedade em uma resposta
Por outro lado, uma mudança aditiva pode ser feita em endpoints estáveis. Elas podem incluir:
- Novos parâmetros opcionais
- Novas propriedades nas respostas. Não consideramos isso uma mudança incompatível porque presumimos que seu código vai ignorar propriedades desconhecidas nas respostas, o que é uma prática comum na comunidade 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 é 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, ou seja, não deve mudar. O Looker não vai lançar mudanças incompatíveis 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 descontinuados:
- Os endpoints Beta estão em desenvolvimento e podem mudar no futuro. Elas não são protegidas contra mudanças incompatíveis. Ao usar endpoints Beta, considere se uma mudança na API Looker seria particularmente prejudicial ao seu app ou ciclo de desenvolvimento. Leia as notas da versão do Looker se você planeja usar um endpoint Beta para ficar por dentro de todas as mudanças.
- Os endpoints descontinuados ainda são compatíveis 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 parar de usar o endpoint descontinuado. Quando uma versão futura do Looker remover o suporte para esse endpoint, qualquer código que ainda o estiver usando vai falhar. Na maioria dos casos, um endpoint descontinuado é substituído por uma funcionalidade aprimorada. Se você descobrir que seu aplicativo está usando uma função ou propriedade descontinuada, é recomendável refatorar 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 são marcados são considerados estáveis.
Tipos de chamadas de API
Os tipos de chamadas de API definidas como chamadas de API de consulta são os seguintes:
- Chamadas necessárias para pipelines de consultas automatizadas
- Chamadas que recebem dados do banco de dados do cliente
- Chamadas que executam consultas SQL ou extraem resultados para conteúdo
Os exemplos incluem:
Os tipos de chamadas de API definidas como chamadas de API de administrador são os seguintes:
- Chamadas necessárias para criar aplicativos, controlar conteúdo em instâncias e realizar tarefas administrativas.
- Chamadas que controlam a instância do Looker (Google Cloud Core)
- Chamadas que realizam gerenciamento de conteúdo, permissões e usuários, administração de instâncias ou extração de conteúdo de várias pastas
Por exemplo:
Migrar para uma nova versão da API
Ao fazer upgrade do SDK do cliente ou do URL da API para uma nova versão, é necessário revisar o código do aplicativo para verificar se você está usando algo que mudou com a nova versão da API. Faça o seguinte:
- Procure no código do aplicativo os nomes atualizados de função, valor e propriedade.
- Verifique se o código do aplicativo é compatível com mudanças nos tipos (como de número inteiro para string).
- Faça uma auditoria do código (consulte a seção Auditoria do código).
Auditoria do código
Em algumas linguagens, as mudanças incompatíveis na API podem ser descobertas no momento da criação 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 estejam em conflito com o código atual vão ficar evidentes graças à verificação de tipo de compilação e às mensagens de erro do compilador.
- Se o aplicativo foi escrito em uma linguagem dinâmica com tipagem flexível (como JavaScript, Ruby e Python), pode ser mais difícil localizar as partes do aplicativo que serão afetadas por mudanças incompatíveis 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 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).