Neste tópico, descrevemos as estratégias de controle de versões usadas pelas APIs do Google. Em geral, essas estratégias se aplicam a todos os serviços gerenciados pelo Google.
Às vezes, é necessário fazer alterações incompatíveis com versões anteriores ou uma violação (também chamdo de "alterações interruptivas"). Esses tipos de alterações podem causar problemas ou falhas no código que tem dependências na funcionalidade original.
As APIs do Google usam um esquema de controle de versão para evitar alterações importantes. Além disso, as APIs do Google disponibilizam algumas funcionalidades somente em determinados níveis de estabilidade, como componentes Alfa e Beta.
Orientação
Todas as interfaces da API do Google precisam fornecer um número da versão principal, que esteja codificado no final do pacote protobuf e incluído como a primeira parte do caminho do URI para APIs REST. Se uma API apresentar uma alteração interruptiva, como remover ou renomear um campo, ela precisará incrementar o número da versão da API para garantir que o código de usuário existente não seja interrompido repentinamente.
Uma nova versão principal de uma API não pode depender de uma versão principal anterior da mesma API. Uma API pode depender de outras APIs, com a expectativa de que o autor da chamada entenda o risco de dependência e estabilidade associado a essas APIs. Nesse cenário, uma versão estável da API precisa depender apenas de versões estáveis de outras APIs.
Versões diferentes da mesma API precisam funcionar ao mesmo tempo em um único aplicativo cliente por um período de transição razoável. Esse período permite que o cliente faça a transição sem problemas para a versão mais recente. Uma versão mais antiga precisa passar por um período razoável e bem comunicado antes de ser encerrada.
Para versões com estabilidade Alfa ou Beta, as APIs precisam anexar o nível de estabilidade após o número da versão principal no pacote protobuf e no caminho do URI usando uma destas estratégias:
- Controle de versão baseado em canal (recomendado)
- Controle de versão baseado em versão
- Controle de versão baseado em visibilidade
Controle de versão com base no canal
Um canal de estabilidade é uma versão de longa duração em um determinado nível de estabilidade que recebe atualizações no local. Não há mais de um canal por nível de estabilidade para uma versão principal. Nessa estratégia, há até três canais disponíveis: Alfa, Beta e Estável.
Os canais Alfa e Beta precisam ter o nível de estabilidade anexado à versão, mas o canal estável não pode ter o nível de estabilidade anexado.
Por exemplo, v1 é uma versão aceitável para o canal stable, mas v1beta ou v1alpha não são. Da mesma forma, v1beta ou v1alpha são versões aceitáveis
para o respectivo canal Alfa e Beta, mas v1 não é aceitável para
nenhum dos dois. Cada um desses canais recebe novos recursos e atualizações "no local".
A funcionalidade do canal beta precisa ser um superconjunto da funcionalidade do canal estável, e a funcionalidade do canal alfa precisa ser um superconjunto da funcionalidade do canal beta.
Suspensão da funcionalidade da API
Os elementos da API (campos, mensagens e RPCs) podem ser marcados como obsoletos em qualquer canal para indicar que não podem mais ser usados:
// Represents a scroll. Books are preferred over scrolls.
message Scroll {
option deprecated = true;
// ...
}
A funcionalidade da API obsoleta não pode passar de alfa para beta nem beta para estável. Em outras palavras, a funcionalidade não pode chegar "pré-suspensa" em nenhum canal.
A funcionalidade do canal Beta pode ser removida depois de ter sido suspensa por um período suficiente. recomendamos 180 dias. Para a funcionalidade que existe apenas no canal alfa, a suspensão de uso é opcional, e a funcionalidade pode ser removida sem aviso prévio. Se a funcionalidade estiver obsoleta no canal alfa de uma API antes da remoção, a API precisa aplicar a mesma anotação e pode usar qualquer período desejado.
Controle de versão baseado em versão
Uma versão individual é uma versão Alfa ou Beta que precisa estar disponível por um período limitado antes de sua funcionalidade ser incorporada ao canal estável, após o qual a versão individual será encerrada. Ao usar a estratégia de controle de versão com base em versão, uma API pode ter qualquer número de liberações individuais em cada nível de estabilidade.
As versões Alfa e Beta precisam ter o nível de estabilidade anexado à versão, seguido por um número de versão incremental. Por exemplo, v1beta1 ou v1alpha5. As APIs precisam documentar a ordem cronológica dessas versões em sua documentação (como comentários).
Cada versão Alfa ou Beta pode ser atualizada no lugar com as alterações compatíveis com versões anteriores. Para versões beta, as atualizações incompatíveis com versões anteriores precisam ser feitas incrementando o número da versão e publicando uma nova versão com a alteração.
Por exemplo, se a versão atual for v1beta1, v1beta2 será lançado em seguida.
As versões Alfa e Beta precisam ser encerradas após a funcionalidade chegar ao canal estável. Uma versão alfa pode ser encerrada a qualquer momento, enquanto uma versão beta precisa permitir que os usuários tenham um período de transição razoável; recomendamos 180 dias.
Controle de versão baseado em visibilidade
A visibilidade da API é um recurso avançado fornecido pela infraestrutura de API do Google. Ela permite que os produtores de API exponham várias visualizações de API externas de uma superfície de API interna, e que cada visualização seja associada a um rótulo de visibilidade de API, como:
import "google/api/visibility.proto";
message Resource {
string name = 1;
// Preview. Do not use this feature for production.
string display_name = 2
[(google.api.field_visibility).restriction = "PREVIEW"];
}
Rótulo de visibilidade é uma string que diferencia maiúsculas e minúsculas e pode ser usada para marcar qualquer
elemento da API. Por convenção, os rótulos de visibilidade precisam sempre usar letras maiúsculas.
Um rótulo PUBLIC implícito é aplicado a todos os elementos da API, a menos que um rótulo de visibilidade
explícito seja aplicado como no exemplo acima.
Cada rótulo de visibilidade é uma lista de permissões. Os produtores de API precisam conceder rótulos de visibilidade aos consumidores da API para que eles usem os recursos da API associados aos rótulos. Ou seja, o rótulo de visibilidade da API é como uma versão da API da ACL.
Vários rótulos de visibilidade podem ser aplicados a um elemento usando uma
string separada por vírgulas (por exemplo, "PREVIEW,TRUSTED_TESTER"). Quando vários
rótulos de visibilidade são usados, o cliente precisa de apenas um desses
rótulos (OR lógico).
Uma única solicitação de API só pode usar um rótulo de visibilidade. Por padrão, é usado o rótulo de visibilidade concedido ao consumidor da API. Um cliente pode enviar solicitações com um rótulo de visibilidade explícito da seguinte forma:
GET /v1/projects/my-project/topics HTTP/1.1
Host: pubsub.googleapis.com
Authorization: Bearer y29....
X-Goog-Visibilities: PREVIEW
Os produtores de API podem usar a visibilidade da API para controle de versão de API, como
INTERNAL e PREVIEW. Um recurso novo da API começa com o rótulo INTERNAL e,
em seguida, passa para o rótulo PREVIEW. Quando o recurso é estável e fica
disponível para todos os usuários, todos os rótulos de visibilidade da API são removidos da definição
da API.
Em geral, a visibilidade da API é mais fácil de implementar do que o controle de versões de API para alterações incrementais. Mas depende de um suporte sofisticado à infraestrutura de APIs. As APIs do Google Cloud costumam usar a visibilidade da API para recursos em pré-lançamento.