Controle de versão

Como um serviço de API pode gerar várias interfaces, a estratégia de controle de versão da API aplica-se no nível da interface, não no nível do serviço. Por conveniência, o termo APIs refere-se a interfaces de API nas seções a seguir.

Nas APIs em rede, é necessário usar o controle de versão semântica. Dado um número de controle de versão MAJOR.MINOR.PATCH, incremente:

  1. a versão MAJOR quando você fizer alterações incompatíveis na API;
  2. a versão MINOR quando você adicionar funcionalidade de maneira compatível com versões anteriores;
  3. a versão PATCH quando você fizer correção de bugs compatível com versões anteriores.

Regras diferentes se aplicam para especificar o número da versão principal dependendo da versão da API:

  • Na versão 1 (v1) de uma API, o número de versão principal precisa ser codificado como o último componente do nome do pacote proto. Por exemplo, google.pubsub.v1. A versão principal poderá ser omitida no nome do pacote proto caso ele contenha interfaces e tipos estáveis que não precisarão de alterações interruptivas. Por exemplo, google.protobuf e google.longrunning.
  • Para todas as versões da API diferentes da v1, o número da versão principal precisa ser codificado como último componente no nome do pacote proto. Por exemplo, google.pubsub.v2.

Em versões pré-GA, como alfa e beta, é recomendável anexar um sufixo ao número da versão. O sufixo deve consistir no nome da versão de pré-lançamento (por exemplo, alfa, beta) e um número de versão de pré-lançamento opcional.

Exemplos de progressão da versão:

Versão Pacote Proto Descrição
v1alpha v1alpha1 A versão alfa v1.
v1beta1 v1beta1 A versão v1 beta 1.
v1beta2 v1beta2 A segunda versão beta da v1.
v1test v1test Uma versão de teste interna com dados falsos.
v1 v1 A versão principal v1, disponibilidade geral.
v1.1beta1 v1p1beta1 A primeira versão beta para alterações menores para v1.
v1.1 v1 A atualização secundária para a versão v1.1.
v2beta1 v2beta1 A versão v2 beta 1.
v2 v2 A versão principal v2, disponibilidade geral.

Os números de versões secundárias e de patch devem ser refletidos na configuração e na documentação da API. Eles não podem ser codificados no nome do pacote proto.

OBSERVAÇÃO: no momento, a plataforma de APIs do Google não é compatível de modo nativo com versões secundárias e de patch. Para cada versão principal da API, há somente um conjunto de documentação e bibliotecas de cliente. Os proprietários precisam documentá-los manualmente por meio da documentação da API e das notas da versão.

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 noção do risco de dependência e estabilidade associado a elas. Uma versão de API estável só precisa depender da versão estável mais recente de outras APIs.

Por um período, diferentes versões da mesma API precisam ser capazes de trabalhar ao mesmo tempo em um único aplicativo cliente. Isso é para ajudar o cliente a transitar sem problemas da versão mais antiga para a versão mais recente da API.

Uma versão antiga da API só deve ser removida depois que o período de suspensão de uso terminar.

Os tipos de dados comuns e estáveis que são compartilhados por muitas APIs, como data e hora, devem ser definidos em um pacote proto separado. Se uma alteração importante for necessária, um novo nome de tipo ou um nome de pacote com uma nova versão principal precisam ser introduzidos.

Compatibilidade com versões anteriores

Determinar o que conta como uma mudança de compatibilidade com versões anteriores pode ser difícil.

As listas abaixo são um ponto de partida de referência rápida, mas se você tiver dúvidas, consulte a página de compatibilidade de projeto para mais detalhes.

Alterações compatíveis com versões anteriores

  • Como adicionar uma interface de API a um serviço de API
  • Como adicionar um método a uma interface de API
  • Como adicionar uma vinculação HTTP a um método
  • Como adicionar um campo a uma mensagem de solicitação
  • Como adicionar um campo a uma mensagem de resposta
  • Como adicionar um valor a um enum
  • Como adicionar um campo de recurso somente para saída

Alterações incompatíveis com versões anteriores

  • Como remover ou renomear um valor de enum, método, campo, interface ou serviço
  • Como alterar uma vinculação HTTP
  • Como alterar o tipo de campo
  • Como alterar um número de campo proto
  • Como alterar o formato de um nome de recurso
  • Como alterar o comportamento visível das solicitações existentes
  • Como alterar o formato do URL na definição de HTTP
  • Como adicionar um campo de leitura/gravação a uma mensagem de recurso
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…