Gouvernance des API

Effectué

La gouvernance des API est définie comme la pratique de définir et d’appliquer des normes, des stratégies et des processus à grande échelle sur toutes les API organisationnelles. L’API Center vous permet d’effectuer cette opération avec :

• Suivi des métadonnées d’API, notamment le titre de l’API, la description, les versions, les définitions et les déploiements. En outre, vous pouvez spécifier vos propres métadonnées d’API personnalisées, telles que les informations de site en direct, le référentiel de contrôle de code source, etc. pour suivre les métadonnées importantes pour votre organisation (affichées dans un module antérieur).
• S’assurer que toutes les API sont conçues pour se conformer aux philosophies de conception des API organisationnelles
• Garantir la détection en temps opportun des versions d’API avec des changements cassants pour les déploiements et la communication transparents avec les consommateurs d’API

Dans cette unité, nous allons voir comment l’API Center vous permet de configurer la gouvernance des API à grande échelle.

Prérequis

Pour régir vos API avec l’API Center, vous devez :

1. Installez Azure CLI.
2. Installer Azure Developer CLI (azd).
3. Inscrivez le fournisseur de ressources Event Grid dans votre abonnement. Si vous devez inscrire le fournisseur de ressources Event Grid, consultez l’article S’abonner aux événements publiés par un partenaire avec Azure Event Grid.

Conformité de conception d’API

Les équipes de plateforme d’API sont souvent responsables de la définition d’un ensemble de directives pour les producteurs d’API. API Center vous permet de codifier les directives relatives aux API en définissant des règles à l'aide du moteur de linting open-source Spectral. Par défaut, l’API Center est fourni avec une règle blob fournie, mais vous pouvez toujours créer vos propres ensembles de règles open source ou tirer parti de la grande communauté d’ensembles de règles open source. Chaque fois qu’une définition d’API est chargée, l’API Center exécute le linter du Specter à l’aide de l’ensemble de règles fourni pour vérifier la conformité de la définition de l’API à la règle. Un rapport de conformité d’API est généré. Vous pouvez l’afficher dans votre centre d’API.

Pour configurer la conformité de la conception d’API pour votre organisation :

1. Clonez le référentiel GitHub et ouvrez-le dans Visual Studio Code.

2. Basculez sur le dossier APICenter-Analyzer dans le dépôt.

3. Dans le dossier resources/rulesets se trouve un fichier oas.yaml. Ce fichier représente votre guide de style d’API actuel. Il peut être modifié en fonction des besoins et des exigences de votre organisation.

4. Authentifiez-vous dans Azure Developer CLI et Azure CLI avec les commandes suivantes :

   azd auth login
   
   az login
   

5. Exécutez la commande suivante pour déployer l’infrastructure de linting sur votre abonnement Azure.

   azd up
   

6. Suivez les invites pour fournir les informations et les paramètres de déploiement nécessaires, comme le nom de l’environnement et le nom du centre d’API. Pour plus d’informations, consultez Exécution de l’exemple avec Azure Developer CLI (azd).

   Remarque

   Le déploiement peut prendre quelques minutes.

7. Une fois le déploiement effectué, accédez à votre centre d’API dans le portail Azure. Dans le menu de gauche, sélectionnez Événements>Abonnements aux événements pour voir l’abonnement aux événements qui a été créé.

Vous pouvez maintenant charger un fichier de définition d’API dans votre centre d’API pour déclencher l’abonnement aux événements et exécuter le moteur de linting.

Gouvernance de l’API décalée vers la gauche

Les initiatives de gouvernance les plus réussies incluent toujours les développeurs eux-mêmes. En appliquant des principes traditionnels à gauche, les équipes de plateforme d’API peuvent s’assurer que les producteurs d’API connaissent exactement les exigences qu’ils doivent respecter pour publier des API au début du cycle de développement. Cela permet de gagner du temps de développement en réduisant la nécessité de corriger les API non conformes ultérieurement dans le cycle de développement.

L’extension de l’API Center pour Visual Studio Code offre aux producteurs d’API une expérience permettant d’exécuter des vérifications de conformité de conception d’API directement dans Visual Studio Code, car l’API est générée. Par ailleurs, les producteurs d’API peuvent utiliser la fonctionnalité de détection de changement cassant pour détecter quand un changement peut entraîner une conversation cassante pour les consommateurs d’API.

Conformité de la conception d’API dans Visual Studio Code

L’extension de l’API Center est intégrée à Spectral, un linter JSON/YAML qui prend en charge OpenAPI et un ensemble de règles personnalisé. L’extension permet aux développeurs de suivre strictement le guide de style d’API fourni ou recommandé, ce qui garantit la cohérence entre toutes les API développées dans différentes équipes.

Remarque

Vous devez installer l’API Center et les extensions Spectral pour utiliser cette fonctionnalité.

Pour activer,

1. Utilisez le raccourci clavier Ctrl+Maj+P pour ouvrir la palette de commandes. Tapez Centre API Azure : Définir un guide de style d’API actif et appuyez sur Entrée.
2. Sélectionnez l’une des règles par défaut proposées ou, si votre organisation dispose déjà d’un guide de style, utilisez Select Local File (Sélectionner un fichier local) ou Input Remote URL (Entrer une URL distante) pour spécifier l’ensemble de règles actif dans Visual Studio Code. Appuyez sur Entrée.

Une fois qu'un guide de style API actif est défini, l'ouverture d'un fichier de spécification basé sur OpenAPI ou AsyncAPI déclenche une opération locale de mise en correspondance dans Visual Studio Code. Les résultats s’affichent à la fois dans l’éditeur et dans la fenêtre Problèmes (Afficher > les problèmes ou Ctrl+Maj+M).

Détection des changements cassants dans Visual Studio Code

Les versions d’API d’expédition qui interrompent les flux de travail de production des consommateurs entraînent une perte de fiabilité et une perte de confiance. L’extension de l’API Center, à l’aide de l’optique, permet aux développeurs de comparer facilement deux versions d’API et de détecter les modifications cassants introduites dans l’API avant le déploiement.

Remarque

Vous devez installer Optic pour utiliser cette fonctionnalité. Installez en utilisant la commande suivante.

*npm install -g @useoptic/optic*

Ainsi,

1. Utilisez le raccourci clavier Ctrl+Maj+P pour ouvrir la palette de commandes. Tapez Azure API Center : détecter les changements cassants et appuyez sur Entrée.
2. Sélectionnez le premier document de spécification d’API à comparer. Les options valides peuvent inclure des spécifications d’API trouvées dans votre centre d’API, un fichier local ou l’éditeur actif dans Visual Studio Code.
3. Sélectionnez le deuxième document de spécification d’API à comparer. Les options valides peuvent inclure des spécifications d’API trouvées dans votre centre d’API, un fichier local ou l’éditeur actif dans Visual Studio Code.

Visual Studio Code ouvre une vue différentielle entre les deux spécifications de l’API. Toutes les modifications cassants s’affichent à la fois dans l’éditeur et dans la fenêtre Problèmes (Afficher > les problèmes ou Ctrl+Maj+M).