Dans un premier article traitant de l’API Management publié le mois dernier, nous avons vu la théorie : les valeurs ajoutées générales que l’on pouvait attendre d’une telle solution. Je vous propose maintenant de passer à la pratique, d’étudier la mise en place concrète, et j’ai choisi pour cela la proposition de Microsoft : Azure API Management.

Dans cet article, nous allons expliquer pourquoi Azure API Management est un produit intéressant, donner le scénario de l’API que nous allons construire, puis brancher des services backends existants sur une nouvelle instance d’Azure API Management.

Un futur article détaillera la configuration et l’utilisation de notre instance, et clôturera ainsi cette série d’articles sur l’API Management.

Au fait, pourquoi Azure API Management ?

Avant de sauter à pieds joints dans cet exercice de travaux pratiques, prenons quelques instants pour décrire le marché de l’API Management et le positionnement d’Azure API Management dans celui-ci.

La dernière étude du Gartner sur le sujet date de Novembre 2016 et positionne comme leaders les offres de CA Technologies, MuleSoft, Apigee, IBM, et TIBCO. L’offre de Microsoft y est mentionnée comme « digne de considération » du point de vue technique mais a été exclue de l’étude pour cause de revenus générés insuffisants vis à vis des critères de l’étude.

Microsoft a donc une offre à la part de marché objectivement modeste, pour grande partie à cause d’un lancement encore relativement récent (la première version date de fin 2014), mais surtout car elle s’est considérablement enrichie au fil des versions pour atteindre aujourd’hui un niveau de couverture fonctionnelle complet.

Elle va bénéficier de la traction de la croissance de l’utilisation d’Azure, et elle constitue un choix naturel pour les entreprises qui ont fait le choix d’héberger leurs plateformes de Web Services dans Azure.

Gageons aussi que Microsoft a su tirer parti de retours d’expériences sur l’utilisation des autres plateformes pour donner toutes les chances à son outil de prendre des parts de marché !

En tant qu’utilisateur d’Azure, et étant donnée la simplicité de mise en place dans cet environnement, nous allons le voir, ce choix s’imposait.

En tant que lecteur de ce blog, vous être aussi probablement plus à même de déployer cette solution…

Scénario (fictif) de mise en place d’Azure API Management

Décrivons maintenant ce que nous allons faire ici avec Azure API Management.

Nous nous plaçons dans un scénario où nous voulons mettre à disposition de développeurs tiers une API exposant des données de produits culturels (livres et albums musicaux).

On suppose que l’architecture des backend services en place s’inscrit dans la mouvance des micro-services : j’ai un service dédié sur le domaine de la musique (https://efademoservicemusic.azurewebsites.net/api/Albums), et un autre service dédié sur le domaine des livres (https://efademoservicebooks.azurewebsites.net/api/Books). Pour ce tutoriel, on a fait une implémentation très basique via ASP.NET WebAPI, mais Azure API Management est agnostique des technologies de développement sous-jacentes, ou de l’hébergement que vous avez choisi (Azure, Amazon, OnPremises) … même si bien entendu les performances seront bien meilleures, et l’intégration plus souple et évoluée si on place toutes nos billes dans Azure.

Chacun de ces services expose des données via le formalisme REST (en JSON et en XML); on se restreint ici à des méthodes GET (une pour récupérer l’ensemble des données, l’autre pour faire une recherche d’un item précis).

Via l’API Management, nous allons pouvoir mettre en place :

• du packaging de services : pour donner accès à nos clients à un package complet ou packages spécifiques musique ou livres (selon un modèle de prix différent, dans la vraie vie) … sans que les services n’aient connaissance de cette différentiation
• du versioning, sans que les services aient eu à spécifier d’informations sur les versions
• du contrôle de charge, pour limiter le nombre de requêtes acceptées par nos services … sans que les services n’aient connaissance de cette fonctionnalité
• de la gestion de cache pour éviter la surcharge de nos services backend
• des outils de tests et la possibilité d’exporter les contrats techniques d’API pour les différents standards du domaine
• des espaces de communication avec les développeurs

Comme vous le voyez, l’idée est de vous faire comprendre que l’API Management va ajouter des fonctionnalités transverses techniques et liées à la commercialisation des services, en laissant les services concentrés sur le métier lui-même.

Le plongeon dans Azure API Management

Nous nous rendons bien sûr en premier lieu sur le portail de gestion Azure.

Afficher le module de gestion appelé « Service Gestion des API » (« API Management Service », en anglais), dans la section « Web + Mobile ».

Cliquons sur « Ajouter » dans ce module.

Rien de bien sorcier : on choisit …

• le nom de notre API, ce qui donnera l’URL de base pour l’appeler, en MonAPI.azure-api.net par exemple : ici on prendra efademoapi
• le groupe de ressources Azure auquel rattacher cette API : on va prendre le même groupe que celui où sont nos backend services)
• l’emplacement (datacenter) Azure : rester dans l’emplacement des backends pour éviter les couts
• un nom d’organisation, qui sera affiché sur le portail à destination des développeurs : on va choisir « EFA Company »
• l’email de de l’administrateur de l’API, qui recevra les notifications émises par le produit
• le niveau tarifaire, entre développeur , Standard, Premium

Ce qui donne donc …

On clique sur « Créer », et c’est parti pour le déploiement de ce nouveau service. Quelques poignées de minutes plus tard (compter une bonne demi-heure, ça paraît un peu long mais c’est normal), on peut admirer avec fierté notre travail :

On y voit des informations capitales :

• l’URL de la passerelle, qui est l’URL de base pour appeler notre API : https://efademoapi.azure-api.net/
• l’URL du portail des développeurs (les tiers qui vont utiliser notre API dans leur app) : https://efademoapi.portal.azure-api.net/

Mais pour le moment ce service ne fait rien, comme le montre le portail développeur de la « EFA Company » donc notre fierté se met en berne…

Il faut le relier aux services backends en définissant les API qu’on va exposer.

Le branchement des tuyaux backend

Pour gérer notre petite cuisine, nous allons utiliser le portail de publication, accessible en ajoutant /admin au portail développeur, donc https://efademoapi.portal.azure-api.net/admin.

Depuis le menu APIs, on choisit d’importer une API (« Import API ») :

Et là un formulaire se présente à nous

Pour importer l’API, il faut déjà en donner la spécification technique.

• elle peut venir d’un texte qu’on va copier/coller (clipboard), d’un fichier que l’on va uploder (file), d’une URL qui expose cette spécification (from URL)
• elle sera dans un format standard : WADL ou Swagger pour REST, WSDL pour SOAP.

Attention, il faut que vos backend services exposent cette spécification d’une manière ou d’une autre… Par défaut ASP.NET WebAPI ne produit ni Swagger, ni WADL.

Pour lui faire produire du WADL, un bon tutoriel est disponible ici. Pour lui faire produire du Swagger, voir là (sachant que Swagger est aujourd’hui prépondérant dans l’usage vis à vis de WADL, et crée beaucoup moins de problèmes d’intégration dans Azure API Management que WADL, d’après mon expérience).

Revenons à notre exemple.

Intégrons notre 1er service :

Sur notre premier service offrant des informations sur les livres, les développeurs ont choisi Swagger. On va donc utiliser les options :

• « From URL », puis format Swagger sur l’URL https://efademoservicebooks.azurewebsites.net:80/swagger/docs/v1 (qui contient le JSON Swagger)
• choisir d’exposer cette fonctionnalité dans notre API avec le suffixe books (https://efademoapi.azure-api.net/books).

 

Attention si vous passez par Swagger, car Azure API Management exige d’avoir des identifiants d’opérations distincts dans un même contrat Swagger … et par défaut WebAPI va utiliser une concaténation du nom de contrôleur et du verbe HTTP de la méthode, ce qui produit des doublons dans un même service. Voir cet article, qui vous explique en détail comment passer par l’attribut « ActionName » sur les méthodes des contrôleurs pour vous sortir de l’erreur « Cannot have multiple operations with the same operationId » !

Une fois cet écueil passé, notre premier service est exposé dans l’API !

On procède de la même manière avec notre 2ème service (la musique), via l’URL Swagger https://efademoservicemusic.azurewebsites.net:80/swagger/docs/v1…

et notre 2ème service est importé dans Azure API Management.

En guise de conclusion à ce chapitre, notez bien que le seul prérequis que nous devons imposer aux équipes de développement de services backend pour les intégrer est la fourniture de spécifications techniques Swagger, WADL ou WSDL. Par la suite, toutes les fonctionnalités avancées de gestion d’API se feront via le portail API Management, sans toucher au code d’origine des services

Et maintenant ?

Nous avons maintenant de quoi construire une belle API et l’exposer à un public de développeurs qui va la consommer. C’est ce que nous verrons dans un 3ème et dernier article, en même temps que l’on verra jusqu’où peut configurer le comportement de notre API…

…