Gérer les versions d'une API

Cette page fournit des procédures de configuration et de déploiement détaillées pour modifier le numéro de version de votre API. La procédure à utiliser varie selon que les modifications apportées à votre API sont rétrocompatibles.

  • Si la nouvelle version de votre API comporte des modifications rétrocompatibles, telles que l'ajout de champs ou méthodes, consultez la section Modifications rétrocompatibles.
  • Si votre nouvelle API est passée à une méthode existante qui rompt le code client de votre client, consultez la section Modifications incompatibles.

Pour plus d'informations et pour connaître les bonnes pratiques, consultez la section Gestion du cycle de vie des API.

Modifications rétrocompatibles

Lorsque vous apportez à votre API des modifications rétrocompatibles avec le code client existant, selon les bonnes pratiques, incrémentez le numéro de version mineure de votre API avant de déployer la nouvelle version. Bien que Cloud Endpoints n'exécute qu'une seule version mineure d'une API à la fois, les graphiques et les journaux sous Endpoints > Services affichent le numéro de version. En incrémentant le numéro de version mineure avant le déploiement, les graphiques et les journaux fournissent un historique étiqueté de vos déploiements.

Pour incrémenter le numéro de version mineure :

  1. Dans openapi.yaml, incrémentez le numéro de version mineure dans le champ info.version. Par exemple, si la version actuelle est 1.1, définissez info.version sur 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. Utilisez la Google Cloud CLI pour déployer la configuration de l'API:

    gcloud endpoints services deploy openapi.yaml

  3. Déployez le backend de l'API en utilisant l'ID de configuration renvoyé à l'étape précédente. Pour plus d'informations, consultez la section Déployer le backend de l'API.

Modifications non rétrocompatibles

Lorsque vous effectuez des modifications à votre API induisant une rupture du code client de votre client, selon les bonnes pratiques, vous devez incrémenter le numéro de version majeure de votre API. Cloud Endpoints peut exécuter plusieurs versions majeures d'une API simultanément. En fournissant les deux versions de l'API, vos clients peuvent choisir la version qu'ils souhaitent utiliser et restent libres de définir une migration vers la nouvelle version.

Pour exécuter simultanément les versions existantes et les nouvelles versions d'une API :

  1. Créez des fichiers de configuration OpenAPI distincts pour chaque version à diffuser. Cette procédure utilise les noms de fichiers openapi-v1.yaml et openapi-v2.yaml à des fins d'exemple.

  2. Copiez le contenu de openapi-v1.yaml dans openapi-v2.yaml.

  3. Dans openapi-v1.yaml, configurez les éléments suivants :

    • Définissez le champ info.version sur le numéro de la version existante.
    • Laissez le champ basePath inchangé.

    Exemple :

    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. Dans openapi-v2.yaml, configurez les éléments suivants :

    • Apportez les modifications incompatibles avec les versions antérieures.
    • Définissez le champ info.version sur le numéro de la nouvelle version.
    • Définissez le champ basePath pour inclure le nouveau numéro de version majeure.
    • Supprimez la section x-google-endpoints. Cette section est nécessaire si vous souhaitez spécifier l'adresse IP DNS ou l'option allowCors. Lorsque vous déployez deux versions de l'API avec deux fichiers de configuration yaml, une seule d'entre elles peut être présente dans le fichier x-google-endpoints, mais sa configuration s'applique aux deux versions.

    Exemple :

    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. Utilisez la Google Cloud CLI pour déployer les deux fichiers de configuration de l'API:

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

  6. Déployez un seul backend qui diffuse les deux versions de l'API à l'aide de l'ID de configuration renvoyé à l'étape précédente. Pour plus d'informations, consultez la section Déployer le backend de l'API.

Étapes suivantes