A maioria dos aplicativos é escrita usando alguma forma de um SDK 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. Seu aplicativo vai continuar funcionando mesmo que o Looker faça alterações em novas versões da API. O aplicativo não vai ser afetado pelas 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 aplicativos.
À medida que adicionamos mais recursos e funcionalidades ao Looker, também atualizamos a API REST 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. Na maioria dos casos, adições à API não são alterações interruptivas. Assim, podemos manter a versão atual da API sem afetar os códigos de aplicativo criados na API. O código do aplicativo atual pode simplesmente não estar ciente de novas funções, parâmetros ou recursos que aparecem nas próximas versões do Looker.
Para alterações na API que corrompem o código do aplicativo, 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 que antes, enquanto uma nova versão da API vai ser executada com as mudanças e atualizações. Várias versões da API podem estar lado a lado em uma única instância do Looker. Assim, você pode escolher quando fazer upgrade para a nova versão da API. O código criado para chamar o endpoint antigo vai continuar chamando o endpoint antigo. O novo código chamará a nova versão do endpoint no nível de versão mais recente da API.
Uma exceção é para problemas críticos de segurança. Se descobrirmos um problema crítico de segurança 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 desativar a 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 melhor implementação ou solução, normalmente deixaremos a API atual como está, mas marcaremos os endpoints de API associados como "descontinuados" para indicar que você deve se afastar do endpoint no código do aplicativo.
Mudanças interruptivas e interruptivas na API
Uma alteração interruptiva é algo que exclui ou renomeia um artefato existente de um endpoint de API. Isso pode incluir:
- Alterar ou excluir um nome ou tipo de parâmetro
- Como adicionar um novo parâmetro obrigatório
- Alterar o URL base
- Como mudar ou excluir uma propriedade em uma resposta
Uma mudança 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 esse erro porque presumimos que seu código vai ignorar propriedades desconhecidas nas respostas, o que é uma prática comum na comunidade da API REST.
Quando um endpoint estável da API Looker precisa de uma mudança significativa para avançar com a 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.
Sinalizações de endpoints de 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 em endpoints estáveis, exceto em casos extremos, como para corrigir um problema de segurança.
Outros endpoints da API podem ser sinalizados como Beta ou descontinuado:
- Os endpoints Beta estão em desenvolvimento ativo e podem mudar no futuro. Elas não são protegidas contra alterações interruptivas. Ao usar endpoints Beta, considere se uma mudança na API Looker seria particularmente prejudicial para o app ou ciclo de desenvolvimento. Leia as notas da versão do Looker se você planeja usar um endpoint Beta para ficar sabendo de todas as mudanças.
- Endpoints descontinuados são aqueles 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 esse endpoint. Quando uma versão futura do Looker não oferecer mais suporte a esse endpoint, todos os códigos que ainda estiverem em uso serão corrompidos. 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, é uma boa ideia refatorar seu código para substituir o elemento descontinuado o mais rápido possível.
Os endpoints Beta e descontinuados são marcados dessa forma na API Explorer e na Referência da API 4.0. Os endpoints que não forem marcados serão considerados estáveis.
Como migrar para uma nova versão da API
Quando você optar por atualizar o SDK do seu cliente ou o URL da API para uma nova versão da API, será necessário analisar o código do seu aplicativo para verificar se você depende de algo que foi alterado com a nova versão da API. Faça o seguinte:
- Pesquise no código do aplicativo os nomes atualizados da função, do valor e da propriedade.
- Verifique se o código do aplicativo é compatível com alterações de tipos (como de número inteiro para string).
- Audite o código (consulte a seção abaixo).
Como auditar o código
Para algumas linguagens, as 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 tipada, as mudanças estruturais nos tipos de parâmetro ou resposta em uma nova versão da API que contradizem seu código existente devem ser facilmente aparentes graças à verificação de tipo de compilação e às mensagens de erro do compilador.
- Se o aplicativo for escrito em uma linguagem dinâmica de tipos flexíveis (como JavaScript, Ruby e Python), pode ser mais difícil localizar as partes dele que serão afetadas pelas alterações interruptivas em uma nova versão da API. Esses tipos de linguagem 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 exerçam o código do aplicativo, incluindo chamadas para a API Looker (não chamadas simuladas).