Controle de versão da API

Nesta página, você encontra os procedimentos detalhados de configuração e implantação para alterar o número da versão da API. O procedimento usado depende de as alterações na API serem compatíveis com versões anteriores.

Para mais informações e práticas recomendadas, consulte Gerenciamento do ciclo de vida da API.

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

Ao fazer alterações na API que sejam compatíveis com versões anteriores do código do cliente atual, como prática recomendada, incremente o número da versão secundária da API antes de implantar a nova versão. Ainda que o Cloud Endpoints execute somente uma versão secundária de uma API por vez, os gráficos e os registros em Endpoints > Serviços exibem o número da versão. Ao incrementar o número da versão secundária antes de implantá-la, os gráficos e registros fornecem um histórico rotulado das implantações.

Incrementar o número inferior da versão:

  1. Em openapi.yaml, incremente o número da versão secundária do campo info.version. Por exemplo, se a versão atual for 1.1, defina info.version como 1.2:

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.2"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

  2. Use o Google Cloud CLI para implantar a configuração da API:

    gcloud endpoints services deploy openapi.yaml

  3. Implante o backend da API com a ID de configuração retornada da etapa anterior. Consulte os detalhes em Como implantar o back-end da API.

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

Quando você faz alterações na API que quebram o código de cliente dos seus clientes, a prática recomendada é incrementar o número da versão principal da API. Os endpoints podem executar mais de uma versão principal de uma API ao mesmo tempo. Com as duas versões da API, os clientes podem escolher que versão usar e quando migrar para uma nova.

Para executar a versão nova e a atual de uma API ao mesmo tempo:

  1. Crie arquivos de configuração do OpenAPI separados para cada versão a ser exibida. Este procedimento usa os nomes de arquivo openapi-v1.yaml e openapi-v2.yaml para fins de exemplo.

  2. Copie o conteúdo de openapi-v1.yaml para openapi-v2.yaml.

  3. Em openapi-v1.yaml, configure o seguinte:

    • Defina o campo info.version como o número da versão existente.
    • Deixe o campo basePath como está

    Exemplo:

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.1"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v1"

  4. Em openapi-v2.yaml, configure o seguinte:

    • Faça alterações incompatíveis com versões anteriores.
    • Defina o campo info.version como o novo número de versão.
    • Defina o campo basePath para incluir o novo número da versão principal.
    • Remova a seção x-google-endpoints. Esta seção é necessária se você quiser especificar o endereço IP do DNS ou a sinalização allowCors. Ao implantar duas versões da API com dois arquivos de configuração yaml, apenas um deles pode ter x-google-endpoints, mas a configuração será aplicada às duas versões.

    Exemplo:

    info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "2.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v2"

  5. Use o Google Cloud CLI para implantar os dois arquivos de configuração da API:

    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml

  6. Implante um único back-end que atenda às duas versões da API usando a ID de configuração retornada da etapa anterior. Consulte os detalhes em Como implantar o back-end da API.

A seguir