A maioria dos aplicativos é escrita usando um formulário do 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 continuará funcionando mesmo enquanto o Looker faz alterações nas novas versões da API. Seu aplicativo não será afetado pelas 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 é arquitetada para fornecer estabilidade aos endpoints da API Looker e, portanto, estabilidade para 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 de API, parâmetros e propriedades de tipo de resposta à versão atual da API Looker. Na maioria dos casos, as adições não são interruptivas, então podemos manter a versão atual da API sem afetar os códigos de aplicativo criados na API. O código do aplicativo pode simplesmente não estar ciente das novas funções, parâmetros ou recursos que aparecem nas próximas versões do Looker.
Para as mudanças 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 como antes, enquanto uma nova versão da API será executada 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. Assim, você escolhe quando fazer o upgrade para a nova versão da API. O código existente, criado para chamar o endpoint antigo, continuará chamando para o endpoint antigo. O código novo chamará a nova versão do endpoint no nível de versão mais recente da API.
Uma exceção é o caso de 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 de segurança o mais rápido possível, o que pode incluir a desativação da funcionalidade vulnerável até a solução adequada estar disponível.
Se for necessário 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 de API associados como "descontinuado" para indicar que você precisa se afastar do endpoint no código do seu aplicativo.
Alterações interruptivas e interruptivas na API
Uma alteração quebra é algo que exclui ou renomeia um artefato atual de um endpoint de API. Entre elas estão:
- Mudar ou excluir um nome ou tipo de parâmetro
- Como adicionar um novo parâmetro obrigatório
- Alterar o URL base
- Mudar ou excluir uma propriedade existente em uma resposta
Por outro lado, uma mudança aditiva pode ser feita em endpoints stable. Entre elas estão:
- Parâmetros novos e opcionais
- Novas propriedades nas respostas (não consideramos essa violação, porque consideramos que seu código ignora propriedades desconhecidas nas respostas, o que é uma prática comum na comunidade da API REST).
Se um endpoint da API Looker estável precisar de uma mudança significativa para avançar com nova arquitetura ou funcionalidade, a alteração geralmente será adicionada a um novo endpoint e agrupada em uma nova versão da API para que o endpoint da API atual permaneça inalterado.
Sinalizações de endpoints de API
A maioria dos endpoints de API é considerada estável, o que significa que eles não devem mudar. O Looker não libera alterações interruptivas 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 descontinuado:
- Os endpoints Beta estão em desenvolvimento e podem mudar no futuro. Eles não são protegidos contra alterações interruptivas. Ao usar endpoints Beta, considere se uma mudança na API Looker seria prejudicial para seu app ou ciclo de desenvolvimento. Leia as notas da versão do Looker se quiser usar um endpoint Beta para estar a par de alterações.
- Os endpoints descontinuados 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 o endpoint descontinuado. Quando uma versão futura do Looker remover o suporte a esse endpoint, qualquer código que ainda esteja usando ele será corrompido. Na maioria dos casos, um endpoint descontinuado é substituído por funcionalidades aprimoradas. Se você verificar que o aplicativo está usando uma função ou uma propriedade descontinuada, é recomendável refatorar o código para substituir o elemento descontinuado o mais rápido possível.
Os endpoints Beta e descontinuados são marcados dessa forma no API Explorer e na Referência da API 4.0. Os endpoints que não estiverem marcados são considerados estáveis.
Como migrar para uma nova versão da API
Ao optar por fazer upgrade do SDK ou do URL da API do seu cliente para uma nova versão da API, será necessário revisar o código do aplicativo para ver se você está contando algo que mudou com a nova versão. É necessário fazer o seguinte:
- Pesquise no código do aplicativo os nomes atualizados de funções, valores e propriedades.
- Confirme se o código do seu aplicativo é compatível com alterações de tipos (como números inteiros a strings).
- Audite seu código (consulte a seção abaixo).
Como fazer a auditoria do código
Para algumas linguagens, alterações interruptivas na API podem ser descobertas no tempo de compilação como erros de compilação:
- Se o seu aplicativo estiver escrito em uma linguagem compilada e altamente tipada, as mudanças estruturais nos tipos de parâmetro ou resposta em uma nova versão da API que sejam incompatíveis com seu código existente devem ser aparentes prontamente devido à verificação do tipo de compilação e às mensagens de erro do compilador.
- Se o aplicativo foi escrito em uma linguagem dinâmica vagamente tipada (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 linguagens podem exigir testes de unidade de tempo de execução para encontrar problemas relacionados a mudanças de tipo.
Em todos os casos, a prática recomendada é fazer testes de unidade que exerçam o código do seu aplicativo, incluindo chamadas para a API Looker (não chamadas simuladas).