A maioria dos aplicativos é escrita com alguma forma de um SDK cliente ou possivelmente com 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 continuará funcionando mesmo quando o Looker fizer alterações nas novas versões da API. Seu aplicativo não será afetado por alterações em outras versões da API até que você opte por 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 alterações na API
A API Looker foi projetada para fornecer estabilidade aos endpoints da API Looker e, portanto, estabilidade para seus aplicativos.
Conforme 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 inclusões à API não são alterações interruptivas. Por isso, podemos manter a versão existente da API sem afetar os códigos de aplicativo criados nela. Talvez o código do seu aplicativo não esteja ciente de novas funções, parâmetros ou recursos que serão exibidos nas próximas versões do Looker.
Para alterações na API que corrompem 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 continuará funcionando da mesma forma que antes, enquanto uma nova versão será executada junto com as alterações 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 que foi criado para chamar o endpoint antigo continuará chamando esse antigo. O novo código precisa chamar a nova versão do endpoint no nível mais recente da API.
Uma exceção é para problemas críticos de segurança. Se descobrirmos um problema de segurança crítico relacionado a uma parte específica da API, faremos o que for necessário para atenuá-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 for necessário retirar um recurso, uma função ou uma propriedade para criar 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 se afastar do endpoint no código do aplicativo.
Alterações importantes e aditivas na API
Uma alteração importante é aquela que exclui ou renomeia um artefato existente de um endpoint de API. Ele pode incluir:
- Como alterar ou excluir um nome ou tipo de parâmetro
- Como adicionar um novo parâmetro obrigatório
- Como alterar o URL base
- Alterar ou excluir uma propriedade existente em uma resposta
Uma alteração aditiva, por outro lado, pode ser feita em endpoints estáveis. Eles podem incluir:
- Parâmetros novos e opcionais
- Novas propriedades nas respostas (não consideramos essa falha porque presumimos que seu código 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 alteração significativa para avançar com a 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 de API atual permaneça inalterado.
Sinalizações para endpoints de API
A maioria dos endpoints da API é considerada estável, ou seja, ela não mudará. O Looker não libera alterações interruptivas em endpoints estáveis, exceto em casos extremos, como para corrigir problemas de segurança.
Outros pontos de extremidade da API podem ser sinalizados como beta ou deprecated:
- Os endpoints Beta estão em desenvolvimento ativo e podem mudar no futuro. Eles não estão protegidos contra alterações interruptivas. Ao usar endpoints Beta, considere se uma mudança na API Looker pode causar interrupções no app ou no ciclo de desenvolvimento. Leia as notas da versão do Looker se você quiser usar um endpoint Beta para acompanhar as mudanças.
- Os endpoints obsoletos são endpoints que ainda são compatíveis e podem ser usados no momento, mas vão ser excluídos em uma versão futura. O código antigo que usa um endpoint descontinuado precisa ser atualizado para deixar de usar esse endpoint. Quando uma versão futura do Looker remover a compatibilidade com esse endpoint, todos os códigos que ainda o usarem serão corrompidos. Na maioria dos casos, um endpoint descontinuado é substituído por funcionalidades aprimoradas. Se você descobrir que seu aplicativo está usando uma função ou propriedade obsoleta, é uma boa ideia refatorar seu código para substituir o elemento descontinuado o mais rápido possível.
Os endpoints Beta e obsoletos são marcados como tal na Referência da API. Os endpoints não marcados são considerados estáveis.
Como migrar para uma nova versão da API
Quando você optar por atualizar o SDK do cliente ou o URL da API para uma nova versão da API, será necessário analisar o código do aplicativo para ver se você está contando algo que mudou com a nova versão da API. Lembre-se de fazer o seguinte:
- Pesquise no código do aplicativo a função, o valor e os nomes de propriedade atualizados.
- Verifique se o código do aplicativo é compatível com qualquer alteração nos tipos (como número inteiro para string).
- Audite o código (consulte a seção abaixo).
Como auditar seu código
Para algumas linguagens, alterações interruptivas na API podem ser descobertas no tempo de compilação como erros de compilação:
- Se seu aplicativo for escrito em uma linguagem compilada e fortemente tipificada, as alterações estruturais em tipos de parâmetros ou respostas em uma nova versão da API que estejam em desacordo com o código existente deverão ser facilmente aparentes graças à verificação de tipo de compilação e às mensagens de erro do compilador.
- Se seu aplicativo for escrito em uma linguagem dinâmica de tipo flexível (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 idiomas 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 é fazer testes de unidade que exerçam o código do seu aplicativo, incluindo chamadas à API Looker (não chamadas simuladas).