Gerenciamento do ciclo de vida da API

Nesta página, você vê a descrição dos recursos de controle de versões da API do Cloud Endpoints, além de práticas recomendadas para preparar a API do Endpoints e controlar as versões dela. As informações nesta página são aplicáveis às APIs que usam a especificação OpenAPI (em inglês). No caso das APIs que usam o Cloud Endpoints Frameworks no ambiente padrão do App Engine, consulte Como lidar com o controle de versões da API em Java ou em Python.

Recomendamos que você siga os mesmos princípios básicos que o Google usa para o controle de versão e a preparação do serviço da API:

  • Antes de implantar a versão inicial, faça o seguinte no arquivo de configuração da OpenAPI:

    • Defina o número da versão no campo info.version. Recomendamos usar uma string de versão que inclua uma versão principal e uma secundária. Por exemplo: 1.0.
    • Defina o campo basePath como o número da versão principal. Recomendamos usar um caminho base com a letra v seguida pelo número da versão principal. Por exemplo: /v1.

  • Quando você precisar fazer uma alteração compatível com versões anteriores, como adicionar um novo método, aumente o número da versão secundária (1.2, 1.3 etc.) no campo info.version e implante novamente. Consulte Como controlar a versão de uma API para mais detalhes.

  • Quando você precisar fazer uma alteração em um método atual que quebre o código do cliente, copie o arquivo de configuração da OpenAPI e realize as alterações a seguir:

    • Aumente o número da versão principal (2.0, 3.0 etc.) no campo info.version.
    • Aumente o número da versão principal (/v2, /v3 etc.) no campo basePath.

    Implante as duas versões dos arquivos de configuração da OpenAPI e reimplante o back-end, que agora apresenta as duas versões do método. Consulte Como controlar a versão de uma API para mais detalhes.

  • Implemente todas as versões principais da API em um único back-end. Essa recomendação:

    • simplifica o roteamento, porque as solicitações para uma versão específica são baseadas no caminho, como no exemplo anterior;
    • simplifica a configuração e a implantação. Você usa o mesmo projeto e back-end do Google Cloud em todas as versões principais da API, que são implantadas ao mesmo tempo;
    • mantém os custos baixos ao evitar a execução de back-ends excedentes.

  • Prepare a API em um projeto separado do Google Cloud antes de implantá-la no projeto de produção do Google Cloud. Consulte Como preparar serviços para mais detalhes.

O uso de números de versões principal e secundária no Cloud Endpoints corresponde às definições em Controle de versão semântica (em inglês). Embora o Endpoints não exija que você aumente o número da versão do patch no arquivo de configuração da OpenAPI e implante a configuração ao aplicar uma correção de bug no seu código de back-end, isso é possível, se você quiser.

Recursos para controle de versão do Cloud Endpoints

Com o Extensible Service Proxy (ESP), é possível gerenciar várias versões principais da API simultaneamente em um único back-end e projeto do Google Cloud. Para isso, as APIs não podem ter caminhos sobrepostos. Exemplo:

http://echo-api.endpoints.my-project.cloud.goog/v1/echo
http://echo-api.endpoints.my-project.cloud.goog/v2/echo

Isso permite que seus clientes escolham a versão que querem usar e controlar quando migram para a nova versão. O ESP marca cada solicitação com o número de versão antes de encaminhar a solicitação para o método aplicável no back-end. Como cada solicitação é marcada com um número de versão:

  • Os gráficos e registros em Endpoints > Serviços exibem solicitações de cada versão principal da API e o total agregado em todas as versões. É possível filtrar a visualização para uma versão específica. Isso dá uma ideia clara de quanto tráfego cada versão está recebendo. Os registros podem até mostrar quais clientes estão usando qual versão.

  • Quando você reimplanta a API com uma atualização do número de versão secundária, a atividade subsequente é marcada com o número da nova versão nos gráficos e nos registros. Isso proporciona um histórico das implantações.

  • Quando você remove uma versão de uma API, os gráficos e os registros continuam exibindo dados no período em que a API estava ativa.

Exemplo de ciclo de vida da API

Esta seção descreve a evolução típica de um serviço.

Versão 1

Inicialmente, você implanta a versão 1 do serviço My Awesome Echo API. A API é fornecida por my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. Nos gráficos e registros em Endpoints > Serviços, é possível ver todo o tráfego em 1.0.

Versão 1.1

Seus clientes pedem um novo recurso. Por isso, você resolve acrescentar um novo método. No arquivo de configuração da OpenAPI, você adiciona o novo método e aumenta o número do campo info.version para 1.1. Aumente o número da versão secundária, já que essa alteração não quebra o código do cliente. Você implanta e testa a alteração em um ambiente de preparação para verificar se ela está funcionando.

Em seguida, você implanta a configuração da OpenAPI e o back-end da API no ambiente de produção. A API continua sendo fornecida por my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo, mas agora os autores das chamadas podem fazer solicitações ao novo método. Como você não alterou a interface para os métodos antigos, seus usuários não precisam alterar e reimplantar os clientes. Na verdade, eles podem continuar a enviar solicitações para o método antigo da mesma forma que antes.

Em Endpoints > Serviços, o tráfego transmitido está agora na versão 1.1. Se você selecionar um período anterior para exibição, ele mostrará a versão anterior nos gráficos e nos registros, com um histórico detalhado das implantações.

Versão 2.0

Ao longo do tempo, você percebe que precisa fazer uma alteração incompatível com versões anteriores de um método atual. Como é importante não quebrar o código dos clientes, você decide manter duas versões da API. Nenhuma alteração é feita no método antigo, e você implementa a nova versão do método. Você cria outro arquivo de configuração da OpenAPI para a versão 2.0 e configura a nova versão a ser fornecida por my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. Seu arquivo de configuração da OpenAPI original ainda aponta para a versão antiga do método, enquanto o novo aponta para a nova versão do método.

Você implanta a versão 1 e a versão 2 dos arquivos de configuração OpenAPI ao mesmo tempo e reimplanta o back-end, que agora contém as duas versões do método. Consulte Como controlar a versão de uma API para mais detalhes.

Depois de implantar, a seção Endpoints > Serviços mostra que você está fornecendo duas versões da API e pode ver quanto tráfego cada versão está recebendo. Os clientes v1 podem continuar chamando /v1, mas também podem chamar /v2 para usar a nova versão do método. A forma como você controla as versões no código de back-end depende do framework da API utilizada. Para um exemplo que usa servlets, consulte Amostra do Endpoints e Java com várias versões (em inglês).

Como desativar a versão 1

Com o tempo, à medida que os clientes forem migrando e o tráfego para v1 cessar, você pode parar de fornecer essa versão. Para remover a versão 1 da API, implante apenas o arquivo de configuração da OpenAPI da versão 2 e faça a implantação do back-end novamente. Agora você pode remover com segurança o código que implementou a versão 1 do back-end. Endpoints > Serviços retém os dados históricos da versão 1.x.

Como preparar serviços

Como prática recomendada, prepare atualizações para seu serviço do Endpoints para testá-lo antes que ele chegue aos clientes. Também recomendamos que você crie um projeto separado do Google Cloud para preparar o serviço. Assim, ele fica isolado da produção. Por exemplo, as cotas do Google geralmente são compartilhadas por recursos em um projeto. Portanto, se você colocar o serviço de preparação no mesmo projeto que o serviço de produção (uma repetição errônea, por exemplo), poderá causar uma paralisação no serviço de produção.

Recomendamos que você atribua um nome de projeto do Google Cloud que indique claramente que ele é de preparação. Uma estratégia de nomeação comum é usar o mesmo nome que o do projeto de produção no Google Cloud, mas com -staging no final. Também é possível colocar -prod em projetos de produção para deixar claro que o projeto tem serviços de produção.

Os nomes de serviço no Google Cloud precisam ser exclusivos. Como você especifica o nome do serviço no arquivo de configuração da OpenAPI, é necessário manter arquivos de configuração de API separados nos projetos de preparação e de produção. Se preferir, use um conjunto de arquivos de configuração de API e atribua um método de nomeação de serviço para corresponder ao nome do projeto que está sendo implantado.

A seguir