Gestão do ciclo de vida das APIs

Esta página descreve as funcionalidades de controlo de versões da API Cloud Endpoints e apresenta práticas recomendadas para o controlo de versões e a preparação da sua API Endpoints. As informações nesta página aplicam-se às APIs que usam a especificação OpenAPI. Para APIs que usam frameworks do Cloud Endpoints para o ambiente padrão do App Engine, consulte Processar o controlo de versões da API: Java ou Processar o controlo de versões da API: Python.

Recomendamos que siga os mesmos princípios básicos que a Google usa para o controlo de versões da API e a preparação de serviços:

  • Inclua o seguinte no ficheiro de configuração da OpenAPI antes de implementar a versão inicial:

    • Defina o número da versão no campo info.version. Recomendamos que use uma string de versão que inclua uma versão principal e uma versão secundária, por exemplo, 1.0.
    • Defina o campo basePath para incluir o número da versão principal. Recomendamos que use um caminho base formatado como a letra v seguida do número da versão principal, por exemplo, /v1.

  • Quando precisar de fazer uma alteração compatível com versões anteriores, como adicionar um novo método, incremente o número da versão secundária (1.2, 1.3, etc.) no campo info.version e volte a implementar. Consulte o artigo Controlar versões de uma API para ver detalhes.

  • Quando precisar de fazer uma alteração a um método existente que interrompa o código do cliente, faça uma cópia do ficheiro de configuração da OpenAPI e faça as seguintes alterações:

    • 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.

    Implemente ambas as versões dos ficheiros de configuração da OpenAPI e reimplemente o back-end, que agora tem ambas as versões do método. Consulte o artigo Controlar versões de uma API para ver detalhes.

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

    • Simplifica o encaminhamento porque os pedidos a uma versão específica baseiam-se no caminho, como no exemplo anterior.
    • Simplifica a configuração e a implementação. Usa o mesmo Google Cloud projeto e back-end para todas as versões principais da API e implementa todas as versões da API em simultâneo.
    • Mantém os custos baixos, evitando a execução de back-ends supérfluos.

  • Prepare a sua API num Google Cloud projeto separado antes de a implementar no projeto de produção Google Cloud . Consulte o artigo Serviços de preparação para ver detalhes.

A utilização de números de versão principal e secundária nos Endpoints corresponde às definições na Versão semântica. Embora o Endpoints não exija que incremente o número da versão da correção no ficheiro de configuração da OpenAPI e implemente a configuração quando implementar uma correção de erro no código do back-end, pode optar por fazê-lo se quiser.

Funcionalidades de controlo de versões da Cloud Endpoints API

O proxy de serviço extensível (ESP) tem a capacidade de gerir várias versões principais da sua API em simultâneo num único Google Cloud projeto e back-end, desde que as APIs não tenham caminhos sobrepostos. Por exemplo:

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

Isto permite que os seus clientes escolham a versão que querem usar e controlem quando migram para a nova versão. As etiquetas do ESP marcam cada pedido com o número da versão antes de encaminhar o pedido para o método aplicável no back-end. Porque cada pedido é etiquetado com um número de versão:

  • Os gráficos e os registos em Endpoints > Serviços apresentam pedidos de cada versão principal da API e o total agregado em todas as versões. Pode filtrar a vista para uma versão específica. Isto dá-lhe uma ideia clara da quantidade de tráfego que cada versão está a receber. Os registos podem até indicar que clientes estão a usar que versão.

  • Quando reimplementa a sua API com uma atualização do número de versão secundária, a atividade subsequente é etiquetada com o novo número de versão nos gráficos e nos registos. Isto oferece-lhe um histórico etiquetado das suas implementações.

  • Quando remove uma versão de uma API, os gráficos e os registos continuam a apresentar dados no intervalo de tempo em que a API estava ativa.

Exemplo de ciclo de vida da API

Esta secção descreve uma evolução típica de um serviço.

Version 1

Inicialmente, implementa a versão 1 do serviço My Awesome Echo API. A API é fornecida a partir de my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. Nos gráficos e registos em Pontos finais > Serviços, vê todo o tráfego em 1.0.

Versão 1.1

Os seus clientes pedem uma nova funcionalidade, pelo que adiciona um novo método. No ficheiro de configuração do OpenAPI, adicione o novo método e aumente o campo info.version para 1.1. Incrementa o número da versão secundária porque esta alteração não interrompe o código do cliente. Implementa e testa a alteração num ambiente de teste para garantir que funciona.

Em seguida, implementa a configuração da OpenAPI e o back-end da API no ambiente de produção. A API continua a ser publicada a partir de my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo, mas agora os autores das chamadas podem fazer pedidos ao novo método. Como não alterou a interface para os métodos antigos, os seus clientes não têm de alterar nem reimplementar os respetivos clientes. Os clientes podem continuar a enviar pedidos para o método antigo da mesma forma que antes.

Em Pontos finais > Serviços, o tráfego publicado está agora na versão 1.1. Se selecionar um intervalo de tempo anterior para apresentação, é apresentada a versão anterior nos gráficos e registos, o que fornece um histórico etiquetado das suas implementações.

Versão 2.0

Ao longo do tempo, apercebe-se de que tem de fazer uma alteração incompatível com versões anteriores a um método existente. Uma vez que é importante não interromper o código do cliente dos seus clientes, decide manter duas versões da API. Deixar o método antigo como está e implementar a nova versão do método. Cria outro ficheiro de configuração OpenAPI para a versão 2.0 e configura a nova versão para ser publicada a partir de my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. O ficheiro de configuração OpenAPI original continua a apontar para a versão antiga do método, enquanto o novo ficheiro de configuração OpenAPI aponta para a nova versão do método.

Implementa os ficheiros de configuração OpenAPI da versão 1 e da versão 2 ao mesmo tempo e reimplementa o back-end, que agora contém ambas as versões do método. (Consulte o artigo Controlar versões de uma API para ver detalhes.)

Após a implementação, Endpoints > Serviços mostra que está a publicar duas versões da sua API e pode ver a quantidade de tráfego que cada versão está a receber. Os seus clientes da v1 podem continuar a chamar /v1, mas também podem chamar /v2 para usar a nova versão do método. A forma como processa o controlo de versões no código de back-end depende da framework de API que está a usar. Para ver um exemplo com servlets, consulte o exemplo de endpoints e Java com várias versões.

Desativar a versão 1

Com o tempo, à medida que os seus clientes migram e vê que todo o tráfego para a v1 parou, pode interromper a publicação da mesma. Para remover a versão 1 da sua API, implemente apenas o ficheiro de configuração OpenAPI da versão 2 e reimplemente o back-end. Agora, pode remover em segurança o código que implementou a versão 1 do seu back-end. Endpoints > Services retém os dados do histórico da versão 1.x.

Serviços de preparação

Como prática recomendada, recomendamos que prepare as atualizações do serviço Endpoints para poder testar o serviço antes de este chegar aos seus clientes. Também recomendamos que crie um Google Cloud projeto separado para testar o seu serviço, de modo que fique isolado da produção. Por exemplo, as quotas da Google são geralmente partilhadas por recursos num projeto. Assim, se colocar o serviço de teste no mesmo projeto que o serviço de produção, um ciclo for incorreto, por exemplo, pode causar uma indisponibilidade no serviço de produção.

Recomendamos que crie um Google Cloud nome do projeto que indique claramente que se destina a testes. Uma estratégia de nomenclatura comum é usar o mesmo nome que o nome do projeto de produção, mas com -staging no final. Google Cloud Também pode colocar -prod em projetos de produção para deixar claro que o projeto contém serviços de produção.

Os nomes dos serviços no Google Cloud têm de ser exclusivos. Uma vez que especifica o nome do serviço no ficheiro de configuração da OpenAPI, tem de manter ficheiros de configuração da API separados para os projetos de preparação e produção, ou usar um conjunto de ficheiros de configuração da API e criar um processo em que altera o nome do serviço para corresponder ao nome do projeto para o qual está a fazer a implementação.

O que se segue?