Dans cet article, je souhaite vous faire découvrir Flurl, un petit bijou de librairie .Net qui permet d’écrire de manière très simple et très lisible des clients HTTP dans vos applications.

Flurl ?

La librairie s’appelle Flurl en référence à Fluent URL. Comme vous allez le voir, sa syntaxe d’utilisation est en mode fluent, ce qui la rend extrêmement lisible.

Il s’agit d’un projet open source (source sur GitHub), à la fois stable (le projet a 2 ans), vivant (le dernier commit début juillet 2018), communautaire tout en restant gérable (11 contributeurs), et enfin populaire (1,2 millions de téléchargements !).

Il bénéficie de la caution d’une figure de la communauté .Net, à savoir Scott Hanselman, qui lui a récemment consacré un article sur son blog, et qui ne doit pas y être pour rien pour la popularité de l’outil !

A quoi sert Flurl ?

L’adage dit que les API sont partout, et en effet nous sommes tous amenés à incorporer dans nos applications du code ayant le rôle de client HTTP, et donc à manipuler la classe System.Net.Http.HttpClient.

Flurl se propose d’être une surcouche à HttpClient, pour pouvoir écrire du code manipulant les appels HTTP plus lisible, testable, et donc finalement plus maîtrisable.

L’intérêt que l’on peut y porter est donc large :

• applications consommant des APIs REST (applications mobiles notamment)
• applications offrant une API REST, auquel cas on pourra se servir de la librairie pour écrire des séquences de tests avancés, qu’il serait difficile de produire avec un Postman par exemple (et c’est d’ailleurs sur ce scénario que je l’utilise).

Son intérêt est plus discutable pour l’accès à des ressources exposées en SOAP, car on est alors beaucoup moins confronté à devoir construire plus ou moins manuellement des URL « complexes » ou manipuler des headers HTTP.

Comment intégrer Flurl dans mes projets ?

Pour utiliser Flurl, rien de révolutionnaire, il faut installer les 2 packages NuGet suivants

Flurl		Construction d’URL en syntaxe fluent
Flurl.Http		Pour brancher un client Http sur la construction d’URL

Il est à noter que Flurl.Http va apporter une dépendance à Newtonsoft.JSON (pour offrir la possibilité de sérialiser / désérialiser du JSON dans le cadre des appels HTTP), et qu’il existe des packages NuGet signés pour être en mesure de créer des assemblies .NET avec nommage fort.

Bref, c’est bien complet, et là encore, on voit que la librairie est bien axée sur les API REST plus que SOAP !

Enfin, on notera que son support des déclinaisons de l’environnement .NET est large : .NET framework bien sûr, mais aussi Xamarin, .Net Core, applications universelles Windows (UWP). Cela fait que vous ne serez pas freiné pour l’utiliser dans vos projets !

Assez causé, plongeons dans du code !

Configurons !

Tout commence par une première étape, de configuration de la librairie.

Cette phase de configuration permet de définir le comportement qu’auront les appels HTTP pour chaque famille d’API.

Elle est à faire famille d’API par famille d’API (si je dois configurer l’API Facebook et l’API Instagram, je devrai faire 2 appels pour bien distinguer chaque comportement spécifique), et une seule fois (à faire dans le code d’initialisation de l’application, donc).

Une fois la configuration faite, elle s’appliquera à tous les appels faits via Flurl sur ces APIs.

Allons y, pour un exemple de configuration de l’API de Nutritionix.

Remarquez la syntaxe Fluent : lisible, non ?

1er élément important à comprendre en lisant ce code : chaque configuration de Flurl est associée au contexte d’une chaine de caractère (ici l’URL de base de l’API, _FoodAPIBaseUrl, donc « https://trackapi.nutritionix.com/v2/ »); quand on va ultérieurement faire un appel HTTP via Flurl, c’est via un pattern matching sur l’Url cible que Flurl saura quelle configuration utiliser.

Les réglages

On voit dans le code donné en exemple qu’on a la possibilité de définir du code qui s’exécutera sur les événements dans la chaîne de traitement de l’appel HTTP : avant l’appel, après l’appel, en cas d’erreur (la notion d’erreur étant configurable en renseignant la liste des code HTTP devant être considérés comme un succès). On peut donc facilement introduire une politique de log de tous les appels, ce qui est un plus pour la tracabilité des actions déclenchées par notre application.

On peut aussi

• remplacer la librairie qui s’occupe de la sérialisation / désérialisation JSON (par défaut JSON.Net, comme indiqué précédemment)
• remplacer la librairie qui s’occupe d’encoder les paramètres de l’URL
• indiquer une factory fournissant des objets HttpClient
• définir une valeur de timeout pour les appels HTTP
• définir la politique de cookies (on peut les désactiver)

Les headers HTTP

Enfin, on voit dans l’exemple qu’on a la possibilité de définir les headers HTTP qui seront envoyés avec chaque requête.

On y trouve les types de contenu que l’on accepte en retour, les User Agent et bien entendu les spécifités de l’API adressée (comme ici les identifiants de l’API Nutritionix).

Petit truc à savoir : les « _ » que l’on met dans les noms de headers dans le code C# seront transcrits en « – » à l’exécution. Sur notre exemple, on enverra donc bien des headers attendus par l’API comme « x-app-id » et « x-app-key ».

Comme on le voit, on a ici affaire à une librairie très extensible et nous donnant un contrôle centralisé et fort sur le comportement du client HTTP.

Appelons !

Assez paramétré, appelons notre API…

Et là, c’est quand même simplissime (remarquez de nouveau la syntaxe Fluent…).

On part de la chaîne de caractère représentant la base des URL de l’API, et on appelle les méthodes d’extension de Flurl pour construire l’appel HTTP qui nous convient : ajout de segment d’URL, construction de query string sans avoir à se soucier de l’encodage…

On termine en lançant l’appel (GetJsonAsync), et en demandant en retour notre objet JSON désérialisé dans un objet métier, tout prêt à consommer !

On peut bien sûr modifier à la volée les réglages généraux que l’on a posé sur l’API lors de la configuration.

Conclusion

Je vous invite à tester cette librairie très sympathique et à en apprécier :

• la lisibilité apportée au code
• son extensibilité
• sa simplicité.