Utiliser DevOps et CI/CD pour publier des API

  • Article

S’APPLIQUE À : tous les niveaux de Gestion des API

Compte tenu de la valeur stratégique des API dans l'entreprise, l'adoption des techniques DevOps d'intégration (CI) et de déploiement (CD) continus est devenue un aspect important du développement des API. Cet article décrit les décisions que vous devez prendre pour adopter des principes DevOps pour la gestion des API.

L’API DevOps se compose de trois parties :

Diagramme illustrant le flux API DevOps

Chaque partie du pipeline DevOps de l’API est décrite ci-dessous.

Définition de l’API

Un développeur d’API écrit une définition d’API en fournissant une spécification, des paramètres (tels que la journalisation, les diagnostics et les paramètres principaux) et des stratégies à appliquer à l’API. La définition de l’API fournit les informations requises pour provisionner l’API sur un service Azure Gestion des API. La spécification peut être basée sur une spécification d’API basée sur des normes (par exemple, WSDL, OpenAPI ou GraphQL), ou elle peut être définie à l’aide des API Azure Resource Manager (ARM) (par exemple, un modèle ARM décrivant l’API et les opérations). La définition de l’API change au fil du temps et doit être considérée comme « code source ». Vérifiez que la définition de l’API est stockée sous contrôle de code source et qu’elle a une révision appropriée avant l’adoption.

Il existe plusieurs outils pour aider à produire la définition de l’API :

  • Azure APIOps Toolkit fournit un workflow basé sur un système de contrôle de code source Git (tel que GitHub ou Azure Repos). Il utilise un extracteur pour produire une définition d’API qui est ensuite appliquée à un service Gestion des API cible par un serveur de publication. APIOps prend actuellement en charge les API REST et GraphQL.
  • L’outil dotnet-apim convertit une définition YAML bien formée en modèle ARM pour un déploiement ultérieur. L’outil est axé sur les API REST.
  • Terraform est une alternative à Azure Resource Manager pour configurer des ressources dans Azure. Vous pouvez créer une configuration Terraform (avec des stratégies) pour implémenter l’API de la même façon qu’un modèle ARM.

Vous pouvez également utiliser des outils basés sur l’IDE pour les éditeurs tels que Visual Studio Code afin de produire les artefacts nécessaires pour définir l’API. Par exemple, il existe plus de 30 plug-ins pour la modification des fichiers de spécification OpenAPI sur Visual Studio Code Marketplace. Vous pouvez également utiliser des générateurs de code pour créer les artefacts. Le langage CADL vous permet de créer facilement des blocs de construction de haut niveau, puis de les compiler dans un format de définition d’API standard tel qu’OpenAPI.

Approbation de l’API

Une fois la définition d’API produite, le développeur soumet la définition de l’API pour révision et approbation. Si vous utilisez un système de contrôle de code source git (tel que GitHub ou Azure Repos), la soumission peut être effectuée via une demande de tirage(Pull request). Une demande de tirage informe d’autres personnes des modifications qui ont été proposées à la définition de l’API. Une fois les portes d’approbation confirmées, un approbateur fusionne la demande de tirage dans le référentiel principal pour indiquer que la définition de l’API peut être déployée en production. Le processus de demande de tirage permet au développeur de corriger les problèmes détectés pendant le processus d’approbation.

GitHub et Azure Repos autoriser la configuration des pipelines d’approbation qui s’exécutent lorsqu’une demande de tirage est envoyée. Vous pouvez configurer les pipelines d’approbation pour exécuter des outils tels que :

Notes

Les API Azure doivent être conformes à un ensemble strict de directives que vous pouvez utiliser comme point de départ pour vos propres instructions d’API. Il existe une configuration du spectre pour appliquer les instructions.

Une fois les outils automatisés exécutés, la définition de l’API est examinée par l’œil humain. Les outils ne interceptent pas tous les problèmes. Un réviseur humain garantit que la définition de l’API répond aux critères organisationnels des API, notamment le respect de la sécurité, de la confidentialité et des directives de cohérence.

Publication API

La définition de l’API sera publiée dans un service Gestion des API via un pipeline de mise en production. Les outils utilisés pour publier la définition d’API dépendent de l’outil utilisé pour produire la définition d’API :

  • Si vous utilisez Azure APIOps Toolkit, le kit de ressources inclut un éditeur qui écrit la définition de l’API dans le service cible.
  • Si vous utilisez dotnet-apim, la définition de l'API est représentée comme un modèle ARM. Les tâches sont disponibles pour Azure Pipelines et GitHub Actions pour déployer un modèle ARM.
  • Si vous utilisez Terraform, les outils CLI déploient la définition d’API sur votre service. Il existe des tâches disponibles pour Azure Pipelines et GitHub Actions.

Puis-je utiliser d’autres systèmes de contrôle de code source et CI/CD ?

Oui. Le processus décrit fonctionne avec n’importe quel système de contrôle de code source (bien qu’APIOps exige que le système de contrôle de code source soit basé sur Git). De même, vous pouvez utiliser n’importe quelle plateforme CI/CD tant qu’elle peut être déclenchée par un archivage et exécuter des outils en ligne de commande qui communiquent avec Azure.

Meilleures pratiques

Il n’existe aucune norme industrielle pour la configuration d’un pipeline DevOps pour la publication d’API, et aucun des outils mentionnés ne fonctionnera dans toutes les situations. Toutefois, nous constatons que la plupart des situations sont couvertes par une combinaison des outils et services suivants :

  • Azure Repos stocke les définitions d’API dans un référentiel Git.
  • Azure Pipelines exécute les processus automatisés d’approbation d’API et de publication d’API.
  • Azure APIOps Toolkit fournit des outils et des workflows pour la publication d’API.

Nous avons connu le plus grand succès dans les déploiements de clients et recommandons les pratiques suivantes :

  • Configurez GitHub ou Azure Repos pour votre système de contrôle de code source. Ce choix détermine également votre choix d’exécuteur de pipeline. GitHub peut utiliser Azure Pipelines ou GitHub Actions, tandis que Azure Repos doivent utiliser Azure Pipelines.
  • Configurez un service Azure Gestion des API pour chaque développeur d’API afin qu’il puisse développer des définitions d’API avec le service API. Utilisez la référence SKU de consommation ou de développeur lors de la création du service.
  • Utilisez des fragments de stratégie pour réduire la nouvelle stratégie que les développeurs doivent écrire pour chaque API.
  • Utilisez des valeurs nommées et des back-ends pour vous assurer que les stratégies sont génériques et peuvent s’appliquer à n’importe quelle instance Gestion des API.
  • Utilisez Azure APIOps Toolkit pour extraire une définition d’API opérationnelle à partir du service de développement.
  • Configurez un processus d’approbation d’API qui s’exécute sur chaque demande de tirage. Le processus d’approbation de l’API doit inclure la détection des changements cassant, le linting et les tests d’API automatisés.
  • Utilisez l’éditeur Azure APIOps Toolkit pour publier l’API sur votre service Gestion des API de production.

Consultez Déploiements d’API automatisés avec APIOps dans le Centre des architectures Azure pour plus d’informations sur la configuration et l’exécution d’un pipeline de déploiement CI/CD avec APIOps.

Références