Après avoir vu dans le précédent article du mois de l’API les fondamentaux d’une API, nous allons au travers de ce nouvel article concevoir ensemble votre premier projet d’API. Cet article s’organise sous la forme d’un tutoriel qui vous amènera dans la création de votre projet. 

 

Préparer votre environnement

 

Pour créer notre première API, nous n’aurons besoin ni d’un éditeur de code ni d’un environnement de développement sur notre poste. Nous allons exploiter toute la puissance du Cloud et cela directement à travers un navigateur web. 

En théorie, il est possible de dérouler ce tutoriel à partir de votre tablette ou téléphone, il suffit de disposer d’un compte Microsoft Azure. Si vous n’en avez pas encore, vous pouvez en obtenir un gratuitement. 

Pour démarrer ce projet, nous allons utiliser le .NET Core CLI ainsi que la console intégrée Cloud Shell. 

 

Lancer Cloud Shell sur Azure 

Connectez-vous au portail Azure et cliquez sur le bouton ci-dessous pour lancer un terminal Cloud Shell (carré rouge). 

 

 

 

Installer .Net Core CLI 

Maintenant que vous avez lancé Cloud Shell sur Azure, vous pouvez installer .Net Core CLI. 

Dans votre console, exécuter la commande ci-dessous 

 . <(WGET -Q -O – HTTPS://AKA.MS/BUILD-WEB-API-NET-CORE-SETUP)

 

 

Créer notre premier projet 

C’est maintenant le moment de créer votre premier projet, en effet, pour l’initier, nous allons utiliser la commande « dotnet new » du .Net CLI. 

dotnet new webapi -o eventmanager/src/EventManager.Api

 

Pour naviguer vers votre projet vous pouvez utiliser la commande suivante : 

cd ./eventmanager/src/EventManager.Api

 

Et enfin, pour ouvrir votre projet, utilisez cette commande  : 

code .

 

Lors de la création du projet, voici les différents éléments qui ont été générés dans votre projet : 

•        Controller/ : ce dossier va contenir toutes nos classes dans lesquelles les points d‘entrées (endpoints) vont être exposés. A partir de notre projet de base, un controller « weatherforecast » est ajouté au projet, ce qui permet d’avoir un exemple de test. 

•        Startup.cs : dans cette classe se trouve la configuration de notre service HTTP, comme l’ajout d’une gestion d’autorisations ou d’une gestion des erreurs. 

•        Program.cs : cet objet contient la méthode d’entrée permettant l’initialisation de la Web API. 

 

Tester le projet

Maintenant que vous avez crée votre projet, nous allons dès à présent le tester. Pour ce faire, lancez la commande suivante :

 

Afin de vérifier le bon fonctionnement de notre API, nous allons récupérer les données en appelant l’API sur son URL de test “weatherforecast”. Ainsi, vous pouvez exécuter l‘appel HTTP via la commande suivante : 

curl -k -s https://localhost:5001/weatherforecast | jq

 

Vous obtiendrez alors le résultat ci-dessous, dans notre cas l‘API nous a renvoyé une liste de relevés de températures sous le format standard JSON :  

 

Pour arrêter le service, il suffit simplement d’exécuter cette commande : 

kill $(pidof dotnet)

 

Déployer le projet

Pour faciliter notre test et ne pas avoir à utiliser la commande « curl », nous allons déployer notre projet sur le Cloud Azure. 

Je vous invite à tout d’abord créer une Azure Web App, cette ressource est la plus adaptée pour l’hébergement d’une API sur le Cloud de Microsoft. 

 

Créer l’environnement  

Le déploiement du projet fait, passons à l’étape de création de notre environnement. Commençons par ajouter un Resource Group, ce dernier représente un regroupement logique de ressources sur Azure. 

 

La prochaine étape est la création d’un Service Plan : il s’agit ici d’un container adapté à la capacité de calcul dont à besoin une  API. 

 

 

Enfin, nous pouvons d’ors et déjà créer notre Web App avec la commande présente ci-dessous. Une fois l’application créée, vous allez retrouver en sortie le lien correspondant au repository git local, emplacement lié au code de l’application. Sauvegardez-le car il sera utile pour la suite. 

 

Déployer son application 

Pour déployer l’application, il faut d’abord créer un compte qui nous permettra de déployer notre application. 

 

Ensuite, il faut initialiser le repository et déployer notre projet sur le repository local de notre webapp (pensez à récupérer l’url lors de la précédente étape). 

 

Il est temps d’initialiser notre repos : 

 

On configure maintenant GIT qui est l’utilisateur du repository : 

 

On définit le repository cible avec l’url récupérée lors de la création de l’application :

 

On ajoute enfin nos sources et on le publie : 

 

Pour vérifier que notre projet est bien déployé, vous pouvez le tester directement dans un navigateur web en appelant l‘URL WeatherForecast de notre service : 

• https://eventapimanager.azurewebsites.net/weatherforecast 

 

Ajout du premier controller

Pour notre exemple, nous allons ajouter un controller qui va nous permettre de gérer les opérations CRUD liées aux événements. 

Ainsi, basons-nous sur les verbes HTTP. Par convention, chaque verbe HTTP est lié à une action spécifique, par exemple, le verbe PUT permet de faire une mise à jour sur un objet. On le définit avec l’attribut de méthode [HttpPut].

Dans ce tableau vous pouvez retrouver le tableau de correspondance des verbes et actions :

HTTP action verb	CRUD operation	ASP.NET Core attribute
POST	Create	[HttpPost]
GET	Read	[HttpGet]
PUT	Update	[HttpPut]
DELETE	Delete	[HttpDelete]

 

Pour ajouter un nouveau controller il vous suffit d’exécuter la commande suivante : 

touch ./Controllers/EventsController.cs 

 

Ensuite, collez le code ci-dessous :

 

Déployez et testez-le :

 

Une fois le déploiement terminé, vous pouvez le déployer avec l’URL suivante : 

• https://eventapimanager.azurewebsites.net/events 

 

  

La mise en place de Swagger pour concevoir des services web

 

Qu’est-ce que Swagger ? 

L’outil Swagger est un ensemble d’outils open-source construit autour de la spécification OpenAPI. Ces outils peuvent vous aider à concevoir, construire et documenter des API REST. Swagger utilise la spécification OpenAPI de votre API pour comprendre sa structure. 

Par exemple, l’interface utilisateur de Swagger est un outil qui permet de visualiser la documentation dans un navigateur, pour une API définie avec la spécification OpenAPI. Swagger Codegen, quant à lui, peut prendre la même spécification OpenAPI d’une API et générer des SDK clients. 

 

Pourquoi utiliser Swashbuckle ? 

Swashbuckle est une implémentation open-source de Swagger utilisée pour générer la documentation Swagger pour les API de base .NET. Vous pouvez d’ailleurs retrouver toute la documentation de Swashbuckle sur le blog Microsoft. 

Swashbuckle se compose de trois éléments principaux :

• Swashbuckle.AspNetCore.Swagger : Ce composant est le modèle d’objet Swagger ainsi que l’intergiciel permettant d’exposer les objets SwaggerDocument en tant que points terminaux JSON. 

 

• Swashbuckle.AspNetCore.SwaggerGen : Cette bibliothèque est un générateur de Swagger qui construit des objets SwaggerDocument directement à partir de vos routes, contrôleurs et modèles. Elle est généralement combinée avec le middleware des points terminaux Swagger pour exposer automatiquement Swagger JSON. 

 

• Swashbuckle.AspNetCore.SwaggerUI : Ce package est une version intégrée de l’outil Swagger UI. Il interprète Swagger JSON afin de créer une expérience riche et personnalisable pour décrire les fonctionnalités de l’API web. Il comprend des harnais de test intégrés pour les méthodes publiques. 

 

Comme ces bibliothèques sont ajoutées à votre application, elles génèrent et visualisent la documentation de votre API à partir de la dernière version de votre API. Il s’agit d’une documentation vivante, toujours synchronisée avec le dernier code. 

 

 

Ajouter Swagger au projet 

 

Pour ajouter Swagger à votre projet, il vous faut installer le package nous permettant d’utiliser l’outil. Pour ce faire, utiliser cette ligne de commande : 

dotnet add package Swashbuckle.AspNetCore 

 

Maintenant, vous pouvez ouvrir l’éditeur de code : 

code .

 

Dans le fichier Startup.cs ajouter les directives suivantes : 

 

Puis ajouter le code suivant à la fin de la méthode “ConfigureServices” : 

 

 Et ensuite, à la fin de la méthode “Configure” compléter avec le code suivant : 

 

On Build, Commit et push 

 

Vous pouvez vérifier tout ça en lançant l’url suivante :

https://eventapimanager.azurewebsites.net/swagger/ 

Pour étoffer les informations sur Swagger on peut aussi ajouter plusieurs informations directement en commentaire sur la méthode choisie. Dans ce cas, il faut ajouter des paramètres pour pouvoir générer automatiquement le Swagger XML. 

 Voici les 4 étapes à suivre :

Ouvrez le fichier *.csproj qui a été ajouté : 

 

Puis sur la méthode Get de notre controller Event ajouter les commentaires suivants :

 

On lance un Build, Commit et push 

 

Et enfin, on ouvre le lien suivant : https://eventapimanager.azurewebsites.net/swagger/ 

 

Vous avez crée votre premier projet d’API !  

 

Bravo, vous avez crée votre première API. Tout au long de tutoriel vous avez notamment : 

• Créé votre premier projet d’API,

• Déployé votre projet sur Azure et vous l’avez rendu disponible en ligne,

• Rendu exploitable et conforme aux normes “OpenApi” a l’aide de “Swagger“.

 

Et tout cela en moins d’une vingtaine de minutes. Bien sûr, beaucoup d’aspects n’ont pas été traités dans ce guide, dont un des plus important qui est l’API management. À savoir, la gestion de sécurité des accès et des quotas de service. Pour répondre à ce besoin, Microsoft propose Azure API Management.

Si vous souhaitez en savoir plus sur ce sujet, je vous invite à découvrir la vidéo d’un de nos Meetup portant sur le sujet de l’API Management. 

Ce sujet vous a intéressé ? Retrouvez dès à présent le troisième article de cette série “L’API, un rôle central dans votre stratégie d’entreprise“.