Dans les deux premiers articles de cette série, nous avons vu à quoi servaient les outils d’API Management, et avons montré comment préparer la mise en place d’une API dans le produit Azure API Management.

Dans cet ultime article, je me propose de vous montrer comment exploiter cette instance pour tirer bénéfice de ce type de produit.

Administration de l’API : construction de produits

Quand on publie une API publique, on peut trouver un intérêt à sous diviser son offre en différents produits, afin d’appliquer des modèles économiques fins.

Dans notre scénario, on va créer 2 produits :

• un produit d’appel, qui offre un accès aux données musicales uniquement
• un produit complet, qui offre un accès à toutes les données (musique et livres)

Chacun de ces produits nécessitera l’enregistrement du développeur, qui obtiendra alors des clés d’API… ces clés débloquant toute ou partie des fonctionnalités de notre API.

On part du portail de management, onglet « Products », puis « Add Product »

On veille à cocher « Require subscription » pour que le mécanisme de contrôle d’accès par « subscription key » soit mis en place; notez qu’on peut demander à ce que les enregistrements de développeurs soient validés par l’administrateur pour garder plus de contrôle (ici on va s’en passer).

On crée donc nos 2 produits « Music only product » et « Full product ».

On va ensuite ajouter nos APIs à chacun des produits, en allant dans l’onglet API, en choisissant chaque API et en l’associant aux bons produits.

A partir de ce moment, les APIs sont inaccessibles si je n’inclus pas de subscription key dans ma requête HTTP. (on a en retour une erreur HTTP 401 et un message « Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API« ).

Mon produit peut être rendu visible :

• uniquement aux administrateurs
• aux développeurs enregistrés sur le portail
• aux invités (développeurs non enregistrés)

Nous allons ouvrir les produits aux invités, et les publier.

La visibilité des produits se règle dans l’onglet « visibilité » :

La publication se fait depuis l’écran « Summary » de chaque API.

 

Maintenant, notre API est accessible. Changeons de casquette pour prendre celle du développeur consommateur de notre API.

Le portail développeur : enregistrement

Composante essentielle de tout produit d’API Management, le portail développeur va permettre à cette population de consulter la documentation de nos produits / de nos API, de s’enregistrer pour obtenir des clés d’accès et pouvoir les évaluer en ligne via des consoles de test…

On accède donc à notre portail développeur à l’URL https://efademoapi.portal.azure-api.net/

et on s’enregistre via le lien « SIGN IN », qui nous emmène à « SIGN UP ». L’enregistrement demande à l’utilisateur un mot de passe fort et bloque les robots via un CAPTCHA

Le développeur reçoit alors un lien de vérification par email (attention à la boîte à spam, c’était classé en tant que tel lors de mon dernier test), il clique sur le lien et peut démarrer l’utilisation de l’API.

Le développeur voit alors son profil vide de souscriptions et d’applications… mais cela le remplit d’espoir !

Le portail développeur : souscription aux produits

Nous avons configuré nos produits pour qu’ils nécessitent une souscription.

Le développeur est donc amené à demander une souscription via le portail développeur, en accédant au produit (nous choisisson le produit « Full ») et en cliquant sur « Subscribe ».

Les clés de souscription sont alors visibles sur le portail (rappelons que cela est immédiat car on n’a pas mis de processus de validation sur l’attribution des clés).

Notez qu’il est possible de générer une nouvelle clé via le lien regenerate en cas de compromission d’une clé !

Notez aussi que si nous avions demandé un accès au produit « Music Only », l’accès à l’API des livres nous aurait été refusée avec une erreur HTTP 401, car notre clé de souscription ne correspondait pas à un produit offrant cette API !

Le portail développeur : découverte et test d’une API

Armé de cette clé de souscription d’API, on peut alors tester l’utilisation de l’API, toujours via le portail développeur. On choisit l’API qu’on veut tester via le menu APIS, puis le bouton Try It :

On retrouve le JSON attendu, qui contient la liste des livres exposée par notre API.

Notez que le portail expose également la documentation de l’API de manière uniforme quelle que soit la technologie de documentation technique utilisée par l’équipe de développement des services backend !

Il est même possible d’exporter les contrats techniques en WADL ou en Swagger, là aussi quel que soit le format d’origine du service backend.

 

Le portail développeur : publication d’une application cliente de notre API

Le développeur peut déclarer sur le portail les applications clientes qu’il a réalisées et qui consomment notre API, afin de « faire de la publicité » pour celles ci, qui apparaissent alors sur le portail.

Pour cela, il clique sur « Register application », et décrit son app : titre, description, besoins, catégorie, URL. Grâce à cette description, l’administrateur de l’API pourra décider ou non d’autoriser l’app, s’il a mis en place une validation app par app.

Je crée 2 applications (l’une qui n’utilise que la musique et l’autre qui utilise musique & livre), et je les soumets à l’approbation de l’administrateur via le bouton « Submit ».

L’administrateur de l’API voit alors arriver l’application à approuver, et une fois l’approbation émise, l’application s’affiche sur le portail développeur.

Le portail développeur : gestion de tickets

Les développeurs utilisant notre API peuvent découvrir des problèmes, se poser des questions sur son utilisation ou avoir des suggestions d’évolution pour la suite; pour gérer cela, Azure API Management offre un système de ticketing accessible depuis le portail développeur.

La saisie d’un ticket à destination de l’administrateur de l’API :

Un dialogue peut donc s’instaurer entre les développeurs de l’API et les développeurs utilisant l’API, ce qui va simplifier la vie courante de ces équipes et accélérer la réactivité dans la mise en place de correctifs de notre API.

Le portail développeur : statistiques d’utilisation

Les développeurs consommant notre API peuvent accéder aux statistiques d’utilisation correspondant à chacune de leur souscription, ce qui est bien utile dans le cas où la souscription est payante et/ou facturée à l’usage.

Ces statistiques sont accessibles via le lien « Analytics » du profil développeur.

On y trouve :

• évolution dans le temps du nombre d’appels, avec taux d’erreurs et temps de réponse
• répartition par produit, par souscription, par API, par opération dans chaque API
• répartition des appels par pays
• bande passante consommée

Les statistiques sont disponibles sur les 90 derniers jours dans le portail.

Administration de l’API : statistiques d’utilisation

L’administrateur de l’API a, via le site de publication, accès à des statistiques d’usage très similaires à celle que nous venons de décrire pour le profil développeur/utilisateur de l’API.

En sus, il a bien entendu possibilité de rechercher les développeurs les plus consommateurs de l’API pour détecter les éventuels abus.

Administration de l’API : les stratégies (bridage, cache etc…)

Les stratégies (policies en anglais) sont un concept extrêmement riche qui apporte toute la puissance et la flexibilité de la solution Azure API Management.

Une policy est un comportement. Ce comportement est défini pour un scope donné, qui peut aller de l’API complète (tous les produits), jusqu’à une opération d’une API donnée dans un produit donné. On peut donc avoir, si nécessaire, une granularité très fine dans la configuration du comportement de nos APIs.

Ce comportement à trait aux propriétés suivantes :

• autorisation des requêtes cross domain
• règles d’authentification à vérifier sur l’appel : Basic, Client Certificate
• vérification du contenu d’un header HTTP spécifique
• conversion JSON vers XML ou réciproquement
• remplacement de contenu
• recours au cache pour répondre à la requête
• instauration d’une limite dans le rythme d’appels ou dans le total d’appels pour clé de souscription ou par clé
• consignation de l’appel (log) dans Event Hub
• restriction des appels à certaines IP
• rewriting d’URL
• retour d’une réponse en dur
• enrichissement de la requête avant transmission au service backend : ajout de paramètre dans la query string, ajout de header HTTP
• transformation du XML renvoyé par le backend via XSLT

On peut donc enrichir très finement le comportement de l’API, là encore sans demander aux développeurs des services backend d’écrire une seule ligne de code pour ces considérations transverses.

Dans l’exemple ci-dessous, on ajoute un quota de 100 appels par heure sur notre produit d’appel « Music Only ». Comme vous le voyez, cela se fait par saisie de code XML définissant le comportement désiré.

Si je dépasse mon quota, j’ai alors en retour un code HTTP 403 et un message qui m’indique à partir de quand mon quota sera de nouveau utilisable :

L’étendue de ce que l’on peut faire avec ces stratégies est très vaste. Si vous voulez en savoir plus, la documentation exhaustive est la page à visiter !

Administration de l’API : gestion des versions

Il est très facile de gérer de multiples versions des services développés en backend via Azure API Management; en effet, le portail de publication permet de définir des chemins spécifiques qui permettent de s’adresser à une version donnée du service, sans que le consommateur ait à se soucier du serveur qui rendra le service en backend.

Exemple :

• https://efaapiexterne/v1/books renverra vers une version backend de mon service herbergé sur https://serverAinterne/books
• https://efaapiexterne/v2/books renverra vers une version backend 2 de mon service herbergé sur https://serverBinterne/books

Les développeurs n’ont donc pas forcément (même s’ils le peuvent) besoin de se soucier de règle de nommage dans leur conception technique de service, ni dans les règles d’hébergement du service backend. Tout peut être géré par une équipe d’administration de l’API externe. Si vous êtes familiers avec le fonctionnement d’un reverse proxy, on est dans la même philosophie…

Administration de l’API : communication avec les développeurs (tickets, blog, portail)

Sur le portail de publication destiné aux administrateurs du blog, on peut bien entendu gérer les tickets créés par les utilisateurs.

Mais les possibilités de communication avec l’utilisateur de l’API ne s’arrêtent pas là puisqu’il est possible de créer un ou plusieurs blogs qui apparaîtront sur le portail du site.

Il est également possible de rajouter des éléments de contenu sur la page d’accueil du site.

On a donc quasiment un CMS à notre disposition pour gérer notre communication avec les utilisateurs !

Conclusion

J’espère que cette série d’articles vous a fait réaliser l’intérêt de la mise en place d’une solution d’API Management pour offrir des services à valeur ajoutée aux consommateurs de votre API, et simplifier la vie de l’administration de l’API au quotidien.

Pour résumer, la solution d’API Management d’Azure nous a permis :

• d’importer des API backend existantes à partir de leur contrat technique (WADL / Swagger)
• de créer des produits en combinant ces APIs, et de monitorer leur usage
• d’appliquer des règles de contrôle des quotas/débits, et de mettre en place des mécanismes de cache, le tout pour mieux contrôler l’utilisation de mes ressources
• d’offrir aux développeurs consommateurs de l’API un portail complet avec enregistrement, obtention de clés, documentation, outil de test, statistiques d’usages, outils de dialogue avec l’administrateur de la plateforme (blogs, tickets, contenus additionnels).

Il est aussi intéressant de bien garder en tête qu’on a pu dérouler ce scénario sans demander aux équipes de développement backend de toucher une seule ligne de code dans leurs services !

Imaginez la quantité de code à écrire pour retrouver les fonctionnalités que nous avons vu au fil de ces articles !

C’est vendu ?