Comment se matérialise techniquement une API ?

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 :
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 :
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“.
Bonjour,
Sur le début du projet, lors de la présentation de l’arborescence, vous parlez de l’ajout du controleur weatherforecast , mais évidemment celui-ci n”est pas créé à la création du prpjet.
Ou récupérer le code de ce controleur ?
J’en suis à cette étape, je peux tout de même tester le projet en invoquant localhost:5001/api/Values pour avoir les données en dur renvoyées par le controleur créé par défaut.
Merci de votre aide.
Bonjour
le contrôleur “WeatherForecastControler” est ajouté automatiquement au projet si vous utilisez un template de projet Web Api Core 3.X
Pour les versions antérieures à la 3.0 c’est un contrôleur “ValuesControler” qui est ajouté à des fins d’exemple et de test
pour le code source du contrôleur “WeatherForecast”, vous pouvez le récupérer d’ici :
https://github.com/dotnet/AspNetCore.Docs/blob/master/aspnetcore/tutorials/first-web-api/samples/3.0/TodoApi/Controllers/WeatherForecastController.cs
et pour le modèle là : https://github.com/dotnet/AspNetCore.Docs/blob/master/aspnetcore/tutorials/first-web-api/samples/3.0/TodoApi/WeatherForecast.cs
Cordialement