Cette page s'applique à Apigee et à Apigee hybrid.
Cet article explique ce que vous devez savoir sur la création et la gestion des versions dans le hub d'API.
Qu'est-ce qu'une version ?
Chaque ressource d'API dans le hub d'API est associée à au moins une version. Vous pouvez considérer une version comme l'état d'une API à un moment donné. Fondamentalement, les versions vous aident à regrouper et à organiser vos API en fonction d'ensembles sous-jacents d'opérations, de déploiements, de spécifications et d'autres attributs, comme illustré dans la figure 1.
Figure 1. Chaque version peut comporter des opérations, des déploiements et d'autres attributs.
Dans le hub d'API, une version représente un regroupement logique d'API. Généralement, mais pas nécessairement, ce regroupement s'articule autour des opérations qu'une API peut effectuer. Prenons par exemple le cas d'une API pour une animalerie. La première version de cette API vous permet d'effectuer des tâches de base, telles que l'ajout, la recherche et la suppression d'un animal dans le magasin. Ce sont des exemples d'opérations.
Le fait d'inclure dans une version un ensemble d'opérations d'API qui sont déployées ensemble est une bonne pratique. Par exemple, une API d'animalerie peut avoir une version qui inclut des opérations d'ajout, de recherche et de suppression, toutes déployées dans les mêmes environnements.
Une autre bonne façon de considérer une version est de se dire qu'elle représente la vision de l'API aux yeux du producteur de l'API. Il s'agit de l'ensemble des fonctionnalités et des capacités que les créateurs de l'API ont intégré et s'attendent à voir déployé avec cette version.
Créer des versions
Supposons que les détails d'une API que vous souhaitez ajouter au hub d'API sont capturés dans une spécification OpenAPI. Si tel est le cas, vous pouvez ajouter cette spécification à une version d'API. En procédant ainsi, le hub d'API analyse la spécification et en extrait des informations, telles que les opérations incluses dans l'API, puis stocke ces informations avec la version. Si vous ne disposez pas de spécification OpenAPI, vous pouvez toujours créer une version, mais vous devrez la renseigner manuellement avec les informations descriptives pertinentes. Un autre cas où le hub d'API permet l'analyse des détails de l'API via l'enregistrement automatique des proxys d'API Apigee.
Vous pouvez importer plusieurs fichiers de spécification d'API dans la même version.
Quand créer une version ?
Si de nouvelles opérations sont ajoutées à une API, la création d'une nouvelle version peut être justifiée, ou non.
Supposons que le producteur d'API ajoute une nouvelle opération à une API et a l'intention de la déployer dans tous les déploiements actuellement associés à la version. Dans ce cas, le producteur peut choisir de ne pas créer de nouvelle version de l'API. En revanche, si le producteur effectue une modification présentant une incompatibilité ascendante (modification destructive) et choisit de l'associer à un nouveau déploiement, créer une nouvelle version peut s'avérer utile.
Comme vous pouvez le constater, le hub d'API vous offre la flexibilité nécessaire pour définir et organiser vos versions d'API de façon à répondre au mieux aux besoins de votre organisation et aux besoins de producteurs d'API spécifiques.
Attributs système
Les versions incluent les attributs système suivants par défaut. Vous pouvez modifier les valeurs associées à ces attributs dans les Paramètres. Pour en savoir plus, consultez la section Gérer les attributs.
| Attribut | Description |
|---|---|
| Lifecycle | Le cycle de vie fait référence à un ensemble ordonné d'étapes qu'une API doit suivre, de la conception à la fin de vie. Comme chaque version d'une API évolue généralement en suivant son propre cycle de vie, nous ne définissons pas directement l'étape du cycle de vie d'une API, mais nous en attribuons une à chaque version. |
| Conformité | Dans Paramètres, vous pouvez définir des valeurs pour représenter les détails de conformité qui intéressent votre équipe ou votre organisation. Pour en savoir plus, consultez la section Gérer les attributs. |
| Accréditation | Dans Paramètres, vous pouvez définir des valeurs pour représenter les détails d'accréditation qui intéressent votre équipe ou votre organisation. Pour en savoir plus, consultez la section Gérer les attributs. |
| Documentation | Lien vers la documentation de l'API à laquelle la version est associée. |
Attributs définis par l'utilisateur
Selon les besoins de votre équipe ou de votre organisation, vous pouvez définir des attributs personnalisés (paires nom/valeur) pour les versions. Consultez la section Gérer les attributs.