A maioria dos aplicativos é criada usando alguma forma de SDK do cliente ou, possivelmente, um URL da API. O SDK do cliente e os URLs da API estão vinculados a uma versão específica da API Looker. O aplicativo vai continuar funcionando mesmo quando o Looker fizer mudanças nas novas versões da API. Ele 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, estabilidade 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 à versão atual da API Looker. Na maioria dos casos, as adições à API não são alterações interruptivas. Assim, podemos manter a versão atual da API sem afetar nenhum código do aplicativo criado nela. O código do aplicativo atual pode simplesmente não reconhecer novas funções, parâmetros ou recursos que aparecem em versões subsequentes 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 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 atual criado para chamar o endpoint antigo vai continuar chamando o endpoint antigo. O novo código precisa chamar a nova versão do endpoint no nível mais recente da versão da API.
Uma exceção a isso é para problemas de segurança críticos. Se descobrirmos um problema de segurança crítico relacionado a uma parte específica da API, faremos o que for necessário para atenuar esse problema de segurança 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, função ou propriedade para abrir caminho para uma implementação ou solução melhor, normalmente deixamos a API atual como está, mas marcamos os endpoints da API associados como "obsoletos" para indicar que você precisa sair 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 existente de um endpoint de API. Ela pode incluir:
- Mudança ou exclusão de um nome ou tipo de parâmetro
- Adição de um novo parâmetro obrigatório
- Mudança do URL base
- Mudança ou exclusão de uma propriedade existente 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 em respostas (não consideramos isso interruptivo porque presumimos que seu código vai ignorar propriedades desconhecidas em respostas, o que é uma prática comum na comunidade da API REST)
Se um endpoint de API 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 da API
A maioria dos endpoints da API é considerada estável, o que significa que não é esperado que eles mudem. O Looker não vai lançar mudanças interruptivas para endpoints estáveis, exceto em casos extremos, como para corrigir um problema de segurança.
Outros endpoints da API podem ser marcados como Beta ou obsoletos:
- Os endpoints Beta estão em desenvolvimento ativo e podem mudar no futuro. Eles não estão protegidos contra mudanças interruptivas. 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 de lançamento do Looker se você planeja usar um endpoint Beta para ficar ciente de quaisquer mudanças.
- Endpoints obsoletos são endpoints que 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 será interrompido. Na maioria dos casos, um endpoint descontinuado será substituído por uma funcionalidade aprimorada. Se você descobrir que seu aplicativo está usando uma função ou propriedade obsoleta, é recomendável refatorar o código para substituir o elemento descontinuado assim que possível.
Os endpoints Beta e obsoletos 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.
Tipos de chamadas de API
Os tipos de chamadas de API definidos como chamadas de API de consulta são os seguintes:
- Chamadas necessárias para pipelines de consulta automatizados
- 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 definidos 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, gerenciamento de permissões e usuários, administração de instâncias ou extração de conteúdo em pastas
Os exemplos incluem:
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 da API, você precisará revisar o código do aplicativo para verificar se está usando algo que mudou com a nova versão da API. Faça o seguinte:
- Pesquise no código do aplicativo os nomes de função, valor e propriedade atualizados.
- Verifique se o código do aplicativo oferece suporte a mudanças nos tipos (como de número inteiro para string).
- Faça uma auditoria do código (consulte a seção Como fazer uma auditoria do código).
Como fazer uma auditoria do código
Para algumas linguagens, as mudanças interruptivas na API podem ser descobertas no momento da criação como erros de compilação:
- Se o aplicativo for criado 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 serão facilmente aparentes graças à verificação de tipo de compilação e às mensagens de erro do compilador.
- Se o aplicativo for criado em uma linguagem dinâmica de tipagem fraca (como JavaScript, Ruby e Python), pode ser mais difícil localizar as partes do aplicativo que serão afetadas por mudanças interruptivas em uma nova versão da API. Esses tipos de linguagem podem exigir testes de unidade de ambiente 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).