Pourquoi vous avez besoin d'un portail de développement d'API pour la découverte d'API

Les entreprises s’appuient de plus en plus sur les API pour connecter des applications et des données entre les différents secteurs d’activité, s’intégrer avec des partenaires et offrir des expériences client. Selon TechRadar , aujourd’hui, l’entreprise moyenne exploite un total de 15 564 API, soit une augmentation de 201 % d’une année sur l’autre .

À mesure que le nombre d’API continue de croître , la complexité de la gestion de votre portefeuille d’API augmente. Il devient plus difficile de découvrir et de suivre les API disponibles et où elles se trouvent, ainsi que de trouver de la documentation sur la façon de les utiliser. Sans une stratégie API holistique en place, les API peuvent proliférer plus rapidement que vos équipes Platform Ops ne peuvent les gérer. Nous appelons ce problème la prolifération des API et dans un article précédent, nous avons expliqué pourquoi il s'agit d'une menace si importante. Dans cet article, nous explorons en détail comment vous pouvez lutter contre la prolifération des API en configurant un portail de développeurs d'API avec l'aide de NGINX.

Créez un inventaire de vos API

En fin de compte, les API ne peuvent être utiles que lorsqu’elles sont utilisées, ce qui signifie que les consommateurs d’API ont besoin d’un moyen de les trouver. Sans les systèmes appropriés en place, la prolifération des API rend difficile pour les développeurs de trouver les API dont ils ont besoin pour leurs applications. Dans le meilleur des cas, les listes d’API sont conservées par différents secteurs d’activité et les connaissances sont partagées entre les équipes via des réseaux informels d’ingénieurs.

L’une des premières étapes pour lutter contre la prolifération des API consiste à créer une source unique de vérité pour vos API. Ce processus commence par la création d’un inventaire de vos API. Cependant, réaliser un inventaire précis constitue un défi : il s’agit d’une cible en constante évolution, à mesure que de nouvelles API sont introduites et que les anciennes sont obsolètes. Vous devez également rechercher toutes les « API fantômes » dans vos environnements – des API qui ont été oubliées au fil du temps, qui ont été obsolètes de manière inappropriée ou qui ont été créées en dehors de vos processus standard.

Les API non gérées sont l’un des symptômes les plus insidieux de la prolifération des API, avec à la fois des implications évidentes en matière de sécurité et des coûts cachés. Sans un inventaire précis des API disponibles, vos équipes API doivent passer du temps à rechercher la documentation. Il existe un risque important de duplication inutile des efforts lorsque différentes équipes développent des fonctionnalités similaires. Et les modifications apportées à une API donnée peuvent entraîner des cascades coûteuses de retouches, voire des pannes sans contrôle de version approprié.

Des techniques telles que la découverte automatisée d’API peuvent vous aider à identifier et à traiter les symptômes des API non gérées. Mais pour résoudre le problème, vous devez éliminer les causes profondes : les processus brisés et le manque d’appropriation. En pratique, l’intégration de l’inventaire et de la documentation des API dans vos pipelines CI/CD est la seule approche qui garantit une visibilité sur l’ensemble de votre portefeuille d’API à long terme. Au lieu de devoir suivre manuellement chaque API dès sa mise en ligne, il vous suffit d'identifier et de corriger les exceptions.

Optimisez la découverte d'API avec un portail de développement d'API

La rationalisation de la découverte d’API est un domaine dans lequel un portail de développement d’API peut aider. Il fournit un emplacement central permettant aux consommateurs d'API de découvrir les API, de lire la documentation et d'essayer les API avant de les intégrer dans leurs applications. Votre portail de développeur d'API peut également servir de catalogue d'API central, avec des informations de propriété et de contact, afin que chacun sache qui est responsable de la maintenance des API pour différents services.

Composant essentiel de notre architecture de référence API<.htmla>, un portail de développement API efficace permet quelques cas d'utilisation clés :

• Optimisez la découverte des API – Publiez vos API dans un emplacement accessible afin que les développeurs puissent facilement trouver et utiliser vos API dans leurs projets
• Fournir une documentation claire et à jour – Assurez-vous que les développeurs ont toujours accès à la documentation la plus récente sur le fonctionnement d'une API
• Assurer un contrôle de version approprié – Introduire de nouvelles versions d'une API sans créer de pannes pour les applications en aval, avec prise en charge du contrôle de version
• Générer des informations d'identification d'API – Simplifiez le processus d'intégration afin que les développeurs puissent se connecter et générer des informations d'identification à utiliser pour l'accès à l'API
• Tester les API – Permettre aux développeurs de tester les API sur le portail avant de les intégrer à leurs projets

Dans le cadre de votre stratégie API, vous devez déterminer comment gérer votre portail de développement API. Vous avez besoin d’une approche automatisée et peu interventionniste qui intègre de manière transparente la publication, le contrôle de version et la documentation des API sans créer de travail supplémentaire pour vos équipes API.

Créez une source unique de vérité pour vos API avec NGINX

Pour permettre une découverte transparente des API, vous devez créer une source unique de vérité où les développeurs peuvent trouver vos API, apprendre à les utiliser et les intégrer à leurs projets. Cela signifie que vous aurez besoin d'un portail de développement et d'une documentation à jour .

API Connectivity Manager , qui fait partie de F5 NGINX Management Suite, vous aide à intégrer la publication, le contrôle de version et la documentation des API directement dans vos flux de travail de développement, afin que votre portail de développement d'API ne soit jamais obsolète. En plus de faciliter la création de portails de développeurs API pour héberger vos API et votre documentation, API Connectivity Manager vous permet d'ajouter des pages personnalisées et de personnaliser entièrement le portail des développeurs pour qu'il corresponde à votre image de marque.

Voyons comment API Connectivity Manager vous aide à résoudre certains cas d’utilisation spécifiques. Reportez-vous à la documentation d'API Connectivity Manager pour obtenir des instructions détaillées sur la configuration d'un cluster de portail de développeur et la publication d'un portail de développeur .

Générer automatiquement la documentation de l'API

Il existe souvent un fossé important entre le niveau de qualité et de détail que vos consommateurs d’API attendent de la documentation et ce que vos développeurs d’API occupés peuvent réellement fournir avec un temps et des ressources limités. De nombreux outils de documentation développés en interne ne parviennent pas à s’intégrer au cycle de vie de développement ou à d’autres systèmes d’ingénierie. Ce n’est pas forcément le cas.

Comment NGINX peut vous aider : API Connectivity Manager utilise la spécification OpenAPI pour publier des API sur la passerelle API et générer automatiquement la documentation qui l'accompagne sur le portail des développeurs, ce qui permet aux développeurs d'API de gagner du temps et de garantir que les consommateurs d'API peuvent toujours trouver ce dont ils ont besoin. Vous pouvez télécharger les fichiers de spécification OpenAPI directement via l'interface utilisateur d'API Connectivity Manager ou en envoyant un appel via l'API REST. Cela facilite l'automatisation du processus de documentation via votre pipeline CI/CD.

Pour publier de la documentation dans API Connectivity Manager, cliquez sur Services dans la colonne de navigation de gauche pour ouvrir l’onglet Services . Cliquez sur le nom de votre espace de travail ou créez-en un nouveau .

Une fois que vous êtes dans l'espace de travail, cliquez sur API Docs sous la case contenant le nom et la description de votre espace de travail ( exemple-api dans la capture d'écran). Cliquez simplement sur le bouton Ajouter un document API pour télécharger votre fichier de spécification OpenAPI. Cliquez sur le bouton Enregistrer pour publier la documentation sur le portail des développeurs.

Assurer une gestion des versions appropriée

Les changements de version doivent toujours être traités avec précaution, et cela est particulièrement vrai dans les environnements de microservices où de nombreux services peuvent interagir avec une seule API. Sans une approche prudente pour introduire de nouvelles versions et supprimer les anciennes, un seul changement radical peut entraîner une panne en cascade sur des dizaines de microservices.

Comment NGINX peut vous aider : L'utilisation des fichiers de spécification OpenAPI avec API Connectivity Manager permet un contrôle de version facile pour vos API. En plus de définir le numéro de version, vous pouvez fournir une documentation pour chaque version et gérer son statut (dernière version, active, retirée ou obsolète).

Pour publier une nouvelle version d’une API, cliquez sur Services dans la colonne de navigation de gauche. Cliquez sur le nom de votre espace de travail dans le tableau, puis cliquez sur le nom de votre environnement sur la page qui s’ouvre. Ensuite, cliquez sur le bouton + Ajouter un proxy . À partir de là, vous pouvez télécharger la spécification OpenAPI, définir le chemin de base et la version pour créer l'URI (par exemple, /api/v2/ ) et saisir d'autres métadonnées importantes. Cliquez sur le bouton Publier pour enregistrer et publier votre proxy API.

La version originale de l'API reste disponible parallèlement à votre nouvelle version. Cela donne à vos utilisateurs le temps de migrer progressivement leurs applications ou services vers la version la plus récente. Lorsque vous êtes prêt, vous pouvez abandonner complètement la version d'origine de votre API. La figure 2 montre deux versions de l'API Sentence Generator publiées et en production.

Générer les informations d'identification de l'API

Pour favoriser l’adoption de vos API, vous devez rendre le processus d'intégration aussi simple que possible pour vos consommateurs d’API. Une fois que les utilisateurs ont trouvé leurs API, ils ont besoin d’une méthode pour se connecter en toute sécurité au portail des développeurs et générer des informations d’identification. Ces informations d’identification leur permettent d’accéder aux fonctionnalités de votre API. Le plus souvent, vous souhaiterez mettre en œuvre un flux de travail autogéré afin que les utilisateurs puissent s’inscrire eux-mêmes.

Comment NGINX peut vous aider : API Connectivity Manager prend en charge les workflows API autogérés sur le portail des développeurs afin que les utilisateurs puissent générer leurs propres informations d’identification de ressources pour accéder aux API. Les informations d'identification des ressources peuvent être gérées sur le portail à l'aide de clés API ou d'une authentification HTTP de base . Vous pouvez également activer l’authentification unique (SSO) sur le portail des développeurs pour sécuriser l’accès et permettre aux consommateurs d’API authentifiés de gérer les informations d’identification des ressources.

Pour activer rapidement SSO sur le portail des développeurs, cliquez sur Infrastructure dans la colonne de navigation de gauche. Cliquez sur le nom de votre espace de travail dans le tableau (dans la Figure 3, il s'agit de team-phrase ).

Dans le tableau de la page Espace de travail, cliquez sur le nom de l’environnement que vous souhaitez configurer (dans la Figure 4, il s’agit de prod ).

Dans la section Clusters du portail des développeurs , cliquez sur l’icône … dans la colonne Actions du portail des développeurs sur lequel vous travaillez et sélectionnez Modifier la configuration avancée dans le menu déroulant. Dans la figure 5, le cluster unique du portail des développeurs est devportal-cluster .

Ensuite, cliquez sur Politiques globales dans la colonne de navigation de gauche. Configurez la politique de partie de confiance OpenID Connect en cliquant sur l’icône … dans la colonne Actions de sa ligne et en sélectionnant Modifier la politique dans le menu déroulant. Pour plus d'informations, consultez la documentation d'API Connectivity Manager .

Testez les API sur le portail des développeurs

Une façon de mesurer le succès de votre stratégie API est de suivre la mesure « temps jusqu'au premier appel API », qui révèle le temps qu'il faut à un développeur pour envoyer une requête de base avec votre API.

Nous avons établi qu'une documentation claire et concise est essentielle comme premier point d'entrée de votre API, où vos utilisateurs acquièrent une compréhension de base de la manière de travailler avec une API. En général, les développeurs doivent ensuite écrire un nouveau code pour intégrer l'API dans leur application avant de pouvoir tester les requêtes API. Vous pouvez aider les développeurs à démarrer beaucoup plus rapidement en leur fournissant un moyen d’interagir directement avec une API sur le portail des développeurs à l’aide de données réelles – en effectuant ainsi leur premier appel d’API sans écrire une seule ligne de code pour leur application!

Comment NGINX peut vous aider : Une fois que vous avez activé SSO pour vos portails de développeurs API Connectivity Manager, les consommateurs d'API peuvent utiliser l'explorateur d'API pour tester les appels d'API sur vos pages de documentation. Ils peuvent utiliser API Explorer pour explorer les points de terminaison, les paramètres, les réponses et les modèles de données de l’API, et tester les appels d’API directement avec leurs navigateurs.

La figure 7 montre l'API Explorer en action – dans ce cas, en train d'essayer l'API du générateur de phrases. L'utilisateur sélectionne les informations d'identification appropriées, crée la demande et reçoit une réponse avec des données réelles de l'API.

Résumé

Les API sont essentielles pour votre organisation. La première étape vers la gouvernance et la sécurisation de vos API commence par faire l’inventaire de chaque API, où qu’elle se trouve. Mais la découverte d’API n’est qu’une partie de la solution : vous devez intégrer l’inventaire, la documentation et la gestion des versions des API à votre cycle de vie de développement et d’ingénierie pour traiter les causes profondes de la prolifération des API.

Démarrez un essai gratuit de 30 jours de NGINX Management Suite, qui inclut l'accès à API Connectivity Manager , NGINX Plus en tant que passerelle API et NGINX App Protect pour sécuriser vos API.