Controlo de versões de uma API

Esta página fornece procedimentos detalhados de configuração e implementação para alterar o número da versão da sua API. O procedimento que usa depende do facto de as alterações à sua API serem retrocompatíveis.

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

Alterações retrocompatíveis

Quando faz alterações à sua API que são compatíveis com versões anteriores do código do cliente existente, como prática recomendada, aumente o número da versão secundária da API antes de implementar a nova versão. Embora o Cloud Endpoints execute apenas uma versão secundária de uma API de cada vez, os gráficos e os registos em Endpoints > Serviços apresentam o número da versão. Ao incrementar o número da versão secundária antes da implementação, os gráficos e os registos fornecem um histórico etiquetado das suas implementações.

Para aumentar o número da versão secundária:

  1. Em openapi.yaml, aumente 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 a CLI Google Cloud para implementar a configuração da API:

    gcloud endpoints services deploy openapi.yaml

  3. Implemente o back-end da API usando o ID de configuração devolvido no passo anterior. Para obter detalhes, consulte o artigo Implementar o back-end da API.

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

Quando faz alterações à sua API que interrompem o código do cliente dos seus clientes, como prática recomendada, aumente o número da versão principal da sua API. Os pontos finais podem executar mais do que uma versão principal de uma API em simultâneo. Ao disponibilizar ambas as versões da API, os seus clientes podem escolher a versão que querem usar e controlar quando fazem a migração para a nova versão.

Para executar as versões existentes e novas de uma API em simultâneo:

  1. Crie ficheiros de configuração da OpenAPI separados para cada versão que precisa de publicar. Este procedimento usa os nomes de ficheiros 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 para o número da versão existente.
    • Deixe o campo basePath inalterado.

    Por 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:

    • Fazer alterações incompatíveis com versões anteriores.
    • Defina o campo info.version com o novo número da versão.
    • Defina o campo basePath para incluir o novo número da versão principal.
    • Remova a secção x-google-endpoints. Esta secção é necessária se quiser especificar o endereço IP do DNS ou a flag allowCors. Quando implementa duas versões da API com dois ficheiros de configuração YAML, apenas um deles pode ter x-google-endpoints, mas a respetiva configuração aplica-se a ambas as versões.

    Por 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 a Google Cloud CLI para implementar ambos os ficheiros de configuração da API:

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

  6. Implemente um único back-end que publique ambas as versões da API usando o ID de configuração devolvido no passo anterior. Para obter detalhes, consulte o artigo Implementar o back-end da API.

O que se segue?