A maioria das aplicações é escrita através de alguma forma de um SDK do cliente ou, possivelmente, um URL da API. Os URLs da API e do SDK do cliente estão associados a uma versão específica da API Looker. A sua aplicação vai continuar a funcionar mesmo quando o Looker faz alterações às novas versões da API. A sua aplicação não é afetada pelas alterações noutras versões da API até optar por atualizar o SDK do cliente (ou modificar o URL da API) para usar a nova versão da API Looker.
Como o Looker faz alterações à API
A API Looker foi concebida para oferecer estabilidade aos pontos finais da API Looker e, por conseguinte, estabilidade às suas aplicações.
À medida que adicionamos mais funcionalidades e capacidades ao Looker, também atualizamos a API REST do Looker para aceder ou gerir essas novas funcionalidades. Para cada lançamento do Looker, adicionamos novas funções, parâmetros e propriedades do tipo de resposta da API à versão atual da API Looker. Na maioria dos casos, as adições à API não são alterações significativas, pelo que podemos manter a versão existente da API sem afetar o código da aplicação existente criado com base na API. O código da aplicação existente pode simplesmente não ter conhecimento de novas funções, parâmetros ou funcionalidades que aparecem em lançamentos subsequentes do Looker.
Para alterações à API que interromperiam o código da aplicação existente, agrupamos essas alterações interruptivas numa nova versão da API. Isto significa que a versão antiga da API continua a funcionar da mesma forma que antes, enquanto uma nova versão da API é executada em paralelo com as alterações e as atualizações. Podem existir várias versões da API lado a lado numa única instância do Looker para que possa escolher quando atualizar para a nova versão da API. O seu código existente criado para chamar o ponto final antigo vai continuar a chamar o ponto final antigo. O novo código deve chamar a nova versão do ponto final no nível da versão da API mais recente.
Uma exceção a esta regra são os problemas de segurança críticos. Se detetarmos um problema de segurança crítico relacionado com uma parte específica da API, faremos tudo o que for necessário para mitigar esse problema de segurança o mais rapidamente possível, o que pode incluir a desativação da funcionalidade vulnerável até que esteja disponível uma solução adequada.
Se precisarmos de descontinuar uma funcionalidade, uma função ou uma propriedade para dar lugar a uma melhor implementação ou solução, normalmente, deixamos a API atual como está, mas marcamos os endpoints da API associados como "descontinuados" para indicar que deve afastar-se do endpoint no código da sua aplicação.
Alterações interruptivas e aditivas à API
Uma alteração destrutiva é algo que elimina ou muda o nome de um artefacto existente de um ponto final da API. Pode incluir:
- Alterar ou eliminar o nome ou o tipo de um parâmetro
- Adicionar um novo parâmetro obrigatório
- Alterar o URL de base
- Alterar ou eliminar uma propriedade existente numa resposta
Por outro lado, pode fazer uma alteração aditiva a pontos finais estáveis. Podem incluir:
- Novos parâmetros opcionais
- Novas propriedades nas respostas (não consideramos isto uma rutura porque assumimos que o seu código vai ignorar propriedades desconhecidas nas respostas, o que é uma prática comum na comunidade de APIs REST)
Se um ponto final da API Looker estável precisar de uma alteração significativa para avançar com uma nova arquitetura ou funcionalidade, a alteração é normalmente adicionada a um novo ponto final e agrupada numa nova versão da API para que o ponto final da API existente permaneça inalterado.
Flags para pontos finais da API
A maioria dos pontos finais da API é considerada estável, o que significa que não se espera que mudem. O Looker não vai lançar alterações significativas para pontos finais estáveis, exceto em casos extremos, como para corrigir um problema de segurança.
Outros pontos finais da API podem ser sinalizados como beta ou descontinuados:
- Os pontos finais beta estão em desenvolvimento ativo e podem mudar no futuro. Não estão protegidas contra alterações que possam causar problemas. Quando usar pontos finais beta, considere se uma alteração à API Looker seria particularmente prejudicial para a sua app ou ciclo de desenvolvimento. Leia as notas de lançamento do Looker se planear usar um ponto final beta para estar a par de quaisquer alterações.
- Os pontos finais descontinuados são pontos finais que ainda são suportados e podem ser usados atualmente, mas vão ser eliminados num lançamento futuro. O código antigo que usa um ponto final descontinuado deve ser atualizado para deixar de usar o ponto final descontinuado. Quando um lançamento futuro do Looker remover o suporte para esse ponto final, qualquer código que ainda o esteja a usar vai deixar de funcionar. Na maioria dos casos, um ponto final descontinuado é substituído por uma funcionalidade melhorada. Se verificar que a sua aplicação está a usar uma função ou uma propriedade descontinuada, é recomendável refatorar o código para substituir o elemento descontinuado assim que possível.
Os pontos finais beta e descontinuados estão marcados como tal no API Explorer e na referência da API 4.0. Os pontos finais que não estão marcados são considerados estáveis.
Migrar para uma nova versão da API
Quando optar por atualizar o URL da API ou do SDK do cliente para uma nova versão da API, tem de rever o código da aplicação para ver se está a usar algo que foi alterado com a nova versão da API. Certifique-se de que faz o seguinte:
- Pesquise no código da aplicação os nomes das funções, dos valores e das propriedades atualizados.
- Verifique se o código da aplicação suporta alterações nos tipos (como de número inteiro para string).
- Audite o seu código (consulte a secção Auditar o seu código).
Auditar o seu código
Para alguns idiomas, as alterações significativas na API podem ser detetadas no momento da criação como erros de compilação:
- Se a sua aplicação estiver escrita num idioma compilado e fortemente tipado, as alterações estruturais aos tipos de parâmetros ou de respostas numa nova versão da API que estejam em desacordo com o seu código existente devem ser facilmente visíveis graças à verificação do tipo de compilação e às mensagens de erro do compilador.
- Se a sua aplicação estiver escrita numa linguagem dinâmica de tipagem flexível (como JavaScript, Ruby e Python), pode ser mais difícil localizar as partes da aplicação que serão afetadas por alterações significativas numa nova versão da API. Estes tipos de idiomas podem exigir testes de unidades de tempo de execução para encontrar problemas relacionados com alterações nos tipos.
Em todos os casos, a prática recomendada é ter testes unitários que testem o código da aplicação, incluindo chamadas para a API Looker (chamadas não simuladas).