Gérer les versions d'une API

Cette page explique comment gérer les versions de votre API et la déployer dans plusieurs versions.

Recommandations pour gérer les versions d'une API

Lors de la gestion des versions de votre API, tenez compte de ces recommandations :

  • Lorsque vous souhaitez introduire une modification incrémentielle n'altérant pas fondamentalement le code de votre API, conservez la numérotation actuelle de l'API et déployez cette modification sur l'API existante.
  • Lorsque vous apportez une modification radicale à votre API, passez à la version d'API supérieure.
  • Pour une protection supplémentaire, incrémentez également la version de l'application App Engine, puis déployez la nouvelle version de l'API sur cette nouvelle version. Ainsi, vous pouvez tirer parti de la flexibilité intégrée d'App Engine pour basculer rapidement entre les différentes versions de cette plate-forme et revenir à d'anciennes versions fonctionnelles si vous rencontrez des problèmes inattendus.

Le tableau suivant illustre la correspondance des versions de l'API backend avec les différentes versions de l'application App Engine :

la version de l'application Version de l'API backend
1
  • v1 --> v1 (2) --> v1 (n)
2
  • v1 (n)
  • v2 --> v2 (2) --> v2 (n)
3
  • v1 (n)
  • v2 (n)
  • v3 --> v3 (2) --> v3 (n)

Comme indiqué dans le tableau, des mises à jour incrémentielles n'altérant pas fondamentalement le code de la v1 de l'API sont déployées, chacune remplaçant la version précédente. Lorsque des modifications majeures sont introduites, la version de l'API est incrémentée à la v2 et déployée dans une nouvelle version de l'application App Engine. Cela vous permet de revenir à la version précédente de l'application si nécessaire.

Le tableau indique que la version 2 de l'application est compatible avec la dernière version v1 et la nouvelle version v2 de votre API. Si vous ne supprimez pas le code v1 existant de votre projet, le déploiement du projet entraînera le déploiement des versions v2 et vl (n) de votre API dans la version 2 de l'application.

Déployer sur plusieurs versions d'application

Lorsque vous déployez l'API backend, l'opération s'effectue sur l'ID du projet Google Cloud que vous avez créé pour votre API. Vous devez également spécifier la version d'App Engine vers laquelle vous effectuez les déploiements. Vous spécifiez la version de l'application App Engine dans l'élément <version> du fichier /WEB-INF/appengine-web.xml. Celle-ci ne correspond pas au numéro de version de l'API backend, que vous spécifiez dans l'attribut version de l'annotation @Api.

apiversions

Comme le montre la figure ci-dessus, il est possible de déployer plusieurs versions d'API sur la même version d'App Engine. Vous pouvez également avoir plusieurs versions d'App Engine pour une application.

Accéder aux versions d'API déployées sur une version de diffusion

La première version d'App Engine sur laquelle vous déployez votre API correspond à la version de diffusion. Cette version s'exécute sous l'URL suivante : http://YOUR_PROJECT_ID.appspot.com, où YOUR_PROJECT_ID représente l'ID du projet Google Cloud. Vous pouvez accéder à toutes les versions d'API déployées sur cette version de l'application App Engine à l'aide de cette URL.

La version de diffusion reste la même jusqu'à ce que vous la modifiiez explicitement, dans le Console Google Cloud

Accéder aux versions d'API déployées sur une version d'application inactive

Si vous devez accéder à des versions d'API qui ne sont pas déployées sur la version d'App Engine actuellement diffusée, utilisez une URL spécifique à la version, semblable à celle-ci :

https://VERSION-dot-YOUR_PROJECT_ID.appspot.com

Remplacez VERSION par votre version d'App Engine et YOUR_PROJECT_ID par votre ID de projet Google Cloud. Par exemple, si vous avez la version 1 de diffusion d'App Engine, mais que vous souhaitez accéder à une version d'API déployée sur la version 2, vous devrez utiliser l'URL suivante : https://2-dot-YOUR_PROJECT_ID.appspot.com.

Pour en savoir plus, consultez la documentation sur App Engine.

Accéder aux versions d'API déployées sur des services inactifs (anciennement "modules")

Si vous devez accéder à des versions d'API qui ne sont pas déployées sur le service App Engine par défaut, utilisez une URL spécifique à un service en langage DOT. Exemple :

https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...

Pour en savoir plus, consultez la documentation sur App Engine.