Gérer le cycle de vie des API

Cette page décrit les fonctionnalités de gestion des versions de l'API Cloud Endpoints, et présente les bonnes pratiques concernant la gestion des versions et la préproduction de votre API Endpoints. Les informations de cette page s'appliquent aux API utilisant la spécification OpenAPI. Pour les API qui utilisent les frameworks Cloud Endpoints pour l'environnement App Engine standard, consultez les pages Gérer les versions d'une API : Java et Gérer les versions d'une API : Python.

Nous vous recommandons de suivre les mêmes principes de base que Google utilise pour la gestion des versions d'API et la préproduction du service :

  • Incluez les éléments suivants dans le fichier de configuration OpenAPI avant de déployer la version initiale :

    • Définissez le numéro de version dans le champ info.version. Nous vous recommandons d'utiliser une chaîne de version comprenant une version majeure et une version mineure, par exemple 1.0.
    • Définissez le champ basePath pour inclure le numéro de version majeure. Nous vous recommandons d'utiliser un chemin d'accès de base prenant la forme d'une lettre v, suivie du numéro de version majeure, par exemple /v1.

  • Lorsque vous devez effectuer une modification rétrocompatible, telle que l'ajout d'une nouvelle méthode, incrémentez le numéro de version mineure (1.2, 1.3, etc.) dans le champ info.version, puis effectuez à nouveau le déploiement. Pour en savoir plus, consultez la page Gérer les versions d'une API.

  • Lorsque vous devez apporter des modifications à une méthode existante qui entraînent la rupture du code client, créez une copie du fichier de configuration OpenAPI et effectuez les opérations suivantes :

    • Incrémentez le numéro de version majeure (2.0, 3.0, etc.) dans le champ info.version.
    • Incrémentez le numéro de version majeure (/v2, /v3, etc.) dans le champ basePath.

    Déployez les deux versions des fichiers de configuration OpenAPI et redéployez le backend, qui contient maintenant les deux versions de la méthode. Consultez la documentation sur la gestion des versions d'une API pour plus de détails.

  • Implémentez toutes les versions majeures de l'API dans un seul backend. Cette recommandation permet de :

    • simplifier le routage car les requêtes vers une version spécifique sont basées sur le chemin d'accès, comme dans l'exemple précédent ;
    • simplifier la configuration et le déploiement. Vous utilisez le même projet et le même backend Google Cloud pour toutes les versions majeures de l'API, et vous déployez toutes les versions de l'API en même temps ;
    • limiter les coûts en évitant l’exécution de backends superflus.

  • Effectuez la préproduction de l'API dans un projet Google Cloud distinct avant de la déployer dans le projet de production Google Cloud. Consultez la section sur les services de préproduction pour plus de détails.

L'utilisation de numéros de versions majeures et mineures dans Cloud Endpoints correspond aux définitions stipulées dans la section sur la gestion sémantique des versions. Si vous le souhaitez, vous pouvez incrémenter le numéro de version corrigée dans le fichier de configuration OpenAPI et déployer la configuration lorsque vous déployez une correction de bug dans le code backend. Toutefois, ces opérations ne sont pas requises par Cloud Endpoints.

Fonctionnalités de gestion des versions pour les API Cloud Endpoints

Le proxy Extensible Service Proxy (ESP) peut gérer plusieurs versions majeures de votre API simultanément dans un même projet et backend Google Cloud tant que les chemins d'accès des API ne se chevauchent pas. Exemple :

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

Cela permet à vos clients de choisir la version qu'ils souhaitent utiliser et exercer un contrôle lorsqu'ils migrent vers la nouvelle version. L'ESP assigne un tag à chaque requête avec le numéro de version avant de la router vers la méthode applicable dans le backend. Cette opération entraîne les conséquences suivantes :

  • Les graphiques et les journaux dans Endpoints > Services affichent les requêtes de chaque version majeure de l'API et le total cumulé pour toutes les versions. Vous pouvez filtrer votre vue pour vous concentrer sur une version spécifique. Cela vous donne une idée précise du trafic généré par chaque version. Les journaux peuvent également indiquer quels clients utilisent quelle version.

  • Lorsque vous redéployez votre API avec une mise à jour de numéro de version mineure, les activités qui surviennent ensuite sont étiquetées avec le nouveau numéro de version dans les graphiques et les journaux. Vous avez ainsi accès à un historique libellé de vos déploiements.

  • Lorsque vous supprimez une version d'API, les graphiques et les journaux continuent d'afficher des données dans la plage correspondant à la période d'activité de l'API.

Exemple de cycle de vie d'une API

Cette section décrit l'évolution typique d’un service.

Version 1

Vous commencez par déployer la version 1 du service API My Awesome Echo. L'API est diffusée depuis my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. À l'aide des graphiques et des journaux dans Endpoints > Services, vous pouvez observer tout le trafic de la version 1.0.

Version 1.1

Vos clients demandent une nouvelle fonctionnalité. En réponse, vous ajoutez une nouvelle méthode. Dans le fichier de configuration OpenAPI, ajoutez la nouvelle méthode et faites passer le champ info.version sur 1.1. Vous pouvez incrémenter le numéro de version mineure, car cette modification ne rompt pas le code client. Déployez et testez vos modifications dans un environnement de préproduction pour vous assurer qu'elles fonctionnent.

Déployez ensuite la configuration OpenAPI et le backend de l'API dans l'environnement de production. L'API est toujours diffusée depuis my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo, mais les appelants peuvent désormais envoyer des requêtes à la nouvelle méthode. Comme vous n'avez pas modifié l'interface avec les anciennes méthodes, vos clients n'ont pas besoin de modifier ni de redéployer leurs codes client. Ils peuvent continuer à envoyer des requêtes à l'ancienne méthode.

Dans Endpoints > Services, le trafic desservi est maintenant celui de la version 1.1. Si vous sélectionnez une période antérieure à afficher, la version précédente est affichée dans les graphiques et les journaux, ce qui fournit un historique libellé de vos déploiements.

Version 2.0

Au fil du temps, il peut arriver que vous deviez apporter à une méthode existante une modification incompatible avec les versions précédentes. Afin d'éviter de rompre le code client des utilisateurs, vous décidez de conserver deux versions de l'API. Laissez l'ancienne méthode telle quelle et mettez en œuvre la nouvelle version de la méthode. Créez un autre fichier de configuration OpenAPI pour la version 2.0 et configurez la nouvelle version à diffuser depuis my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. Le fichier de configuration OpenAPI d'origine pointe toujours vers l'ancienne version de la méthode et le nouveau fichier de configuration OpenAPI pointe vers la nouvelle version de la méthode.

Déployez simultanément la version 1 et la version 2 des fichiers de configuration OpenAPI et redéployez le backend, qui contient maintenant les deux versions de la méthode. (Consultez la section Gérer les versions d'une API pour plus de détails.)

Une fois le déploiement effectué, Endpoints > Services indique que vous utilisez deux versions de l'API et vous pouvez voir le trafic généré par chaque version. Les clients v1 peuvent continuer à appeler /v1, mais ils peuvent aussi appeler /v2 pour utiliser la nouvelle version de la méthode. Votre manière de gérer les versions dans le code backend dépend du framework d'API que vous utilisez. Pour obtenir un exemple d'utilisation de servlets, consultez la page Exemple de Cloud Endpoints et Java avec plusieurs versions.

Désactiver la version 1

À mesure que vos clients migrent et que vous constatez que l'intégralité du trafic de la v1 s'est arrêté, vous pouvez interrompre la diffusion de la version. Pour supprimer la version 1 de l'API, déployez uniquement le fichier de configuration OpenAPI de la version 2 et redéployez le backend. Vous pouvez maintenant supprimer du backend en toute sécurité le code qui implémentait la version 1. Endpoints > Services conserve les données de l'historique de la version 1.x.

Services de préproduction

Il est recommandé d'effectuer la préproduction des mises à jour de votre service Endpoints afin de pouvoir le tester avant que vos clients ne l'utilisent. Nous vous recommandons également de créer un projet Google Cloud distinct pour la préproduction de votre service, de manière à l'isoler de la production. Par exemple, les quotas de Google sont généralement partagés par des ressources au sein d'un projet. Ainsi, si vous placez le service de préproduction dans le même projet que le service de production, une boucle errante, par exemple, peut entraîner une interruption du service de production.

Nous vous recommandons de spécifier un nom de projet Google Cloud qui indique clairement qu'il s'agit d'une préproduction. Une stratégie de dénomination courante consiste à utiliser le même nom que celui de votre projet Google Cloud de production, mais avec -staging à la fin. Vous pouvez également ajouter -prod sur les projets de production pour indiquer clairement que le projet contient des services de production.

Les noms de service sur Google Cloud doivent être uniques. Étant donné que vous spécifiez le nom du service dans le fichier de configuration OpenAPI, vous devez gérer des fichiers de configuration de l'API distincts pour les projets de préproduction et de production, ou utiliser un ensemble de fichiers de configuration de l'API et élaborer une procédure permettant de modifier le nom du service afin qu'il corresponde au nom du projet sur lequel vous effectuez le déploiement.

Étapes suivantes