Versões

Este tópico descreve as estratégias de controle de versão 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 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 os canais alfa e beta respectivos, mas v1 não é aceitável para nenhum deles. 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:

// A representation of a scroll.
// Books are now 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.