Introduction à ASP.NET Core et Création de Votre Première API REST

Contexte du cours : Développement Backend Robuste avec C# et .NET: De l'API REST aux Microservices

1. Introduction

Bienvenue dans ce module consacré à l'un des frameworks de développement backend les plus puissants et polyvalents d'aujourd'hui : ASP.NET Core. Dans le vaste paysage du développement web, la création d'APIs RESTful performantes et maintenables est une compétence fondamentale. ASP.NET Core, avec son héritage C# et sa conception moderne, est un choix de prédilection pour construire des services backend qui peuvent alimenter des applications web, mobiles, desktop, ou même d'autres microservices.

Dans cette leçon, nous allons démystifier ASP.NET Core, comprendre ses avantages pour les APIs REST, et surtout, nous allons construire ensemble votre toute première API REST simple mais fonctionnelle.

Ce que vous apprendrez dans cette leçon :

Qu'est-ce qu'ASP.NET Core et pourquoi est-il si populaire pour les APIs REST.
Les concepts fondamentaux d'une API RESTful.
Comment configurer votre environnement de développement.
Les étapes pour créer un projet d'API Web avec ASP.NET Core.
Comment définir des modèles de données et des contrôleurs pour gérer les requêtes HTTP.
Comment tester votre API.

Prérequis :

Connaissances de base en C# (variables, types de données, classes, méthodes, boucles, conditions).
Compréhension des concepts HTTP (GET, POST, PUT, DELETE, requêtes, réponses).
Avoir une notion de ce qu'est une API.

2. Qu'est-ce que ASP.NET Core ?

ASP.NET Core est un framework open-source, multiplateforme et hautes performances conçu pour créer des applications modernes connectées à internet, qu'il s'agisse d'applications web (MVC, Razor Pages), d'APIs REST, de microservices, ou même d'applications en temps réel avec SignalR.

Son évolution : Historiquement, ASP.NET était étroitement lié à Windows et au .NET Framework. Avec l'avènement de .NET Core (maintenant simplement appelé .NET depuis la version .NET 5), Microsoft a réécrit et repensé le framework pour le rendre :

Multiplateforme (Cross-platform) : Il peut s'exécuter sur Windows, macOS et Linux. C'est un changement majeur qui a ouvert ASP.NET à un public beaucoup plus large.
Haute performance : Conçu pour la vitesse et l'efficacité, ASP.NET Core est régulièrement classé parmi les frameworks web les plus rapides.
Modulaire et Léger : Contrairement à son prédécesseur monolithique, ASP.NET Core est composé de packages NuGet modulaires, ce qui permet aux développeurs de n'inclure que les composants nécessaires, réduisant ainsi l'encombrement et la taille des applications.
Open-source : L'intégralité du code source est disponible sur GitHub, favorisant la transparence et la contribution de la communauté.
Injection de Dépendances (DI) intégrée : Le framework est conçu de manière à faciliter l'injection de dépendances, ce qui promeut des architectures modulaires et testables.

Pour le développement d'APIs REST, ASP.NET Core offre un ensemble robuste de fonctionnalités pour gérer les requêtes HTTP, la sérialisation JSON, la validation des données, et bien plus encore.

3. Pourquoi choisir ASP.NET Core pour les APIs REST ?

Le choix d'un framework pour vos APIs REST est crucial. Voici pourquoi ASP.NET Core est un excellent candidat :

Performance : Sa conception optimisée garantit des temps de réponse rapides et une capacité à gérer un grand nombre de requêtes simultanées.
Écosystème Mature : Bénéficiant de l'écosystème .NET, vous avez accès à une vaste gamme de bibliothèques, d'outils et de services prêts à l'emploi.
Productivité du développeur : Des outils comme Visual Studio et Visual Studio Code, combinés à des fonctionnalités comme l'auto-complétion, le débogage intégré et les modèles de projet, accélèrent considérablement le processus de développement.
Langage C# : C# est un langage moderne, orienté objet, fortement typé, avec une syntaxe claire et des fonctionnalités avancées (LINQ, async/await) qui facilitent le développement d'applications complexes.
Sécurité intégrée : ASP.NET Core propose des mécanismes robustes pour l'authentification et l'autorisation, essentiels pour sécuriser vos APIs.
Tests Unitaires Faciles : Sa conception modulaire et l'utilisation de l'injection de dépendances rendent le code facilement testable.
Communauté Active : Une communauté mondiale de développeurs et le soutien de Microsoft garantissent une abondance de ressources, de documentations et de solutions aux problèmes courants.

4. Concepts Clés d'une API RESTful (Rappel)

Avant de plonger dans le code, faisons un rapide rappel sur ce qu'est une API RESTful et ses principes fondamentaux.

REST (Representational State Transfer) est un style architectural pour les systèmes distribués hypermédia. Une API RESTful adhère à ces principes :

Ressources : Tout est une ressource. Une ressource est une abstraction de toute information à laquelle on peut accéder. Par exemple, /products, /users, /orders. Chaque ressource est identifiée par un URI (Uniform Resource Identifier).
Verbes HTTP (Opérations) : Les opérations sur les ressources sont effectuées en utilisant les verbes HTTP standard :
- GET : Récupérer une ressource ou une collection de ressources. (Lecture)
- POST : Créer une nouvelle ressource. (Écriture)
- PUT : Mettre à jour une ressource existante (remplacer entièrement). (Modification)
- PATCH : Mettre à jour partiellement une ressource existante. (Modification partielle)
- DELETE : Supprimer une ressource. (Suppression)
Statelessness (Sans État) : Chaque requête d'un client vers le serveur doit contenir toutes les informations nécessaires pour que le serveur puisse comprendre et traiter la requête. Le serveur ne doit pas stocker d'informations sur l'état du client entre les requêtes.
Communication Basée sur JSON/XML : Les données sont généralement échangées sous forme de JSON (JavaScript Object Notation) ou, moins fréquemment, de XML. JSON est devenu le standard de facto grâce à sa légèreté et sa lisibilité.
Uniform Interface : Les ressources sont manipulées via une interface uniforme (les verbes HTTP et les URI) qui simplifie l'interaction entre le client et le serveur.

5. Préparation de l'environnement de développement

Pour commencer à développer avec ASP.NET Core, vous aurez besoin de :

Le SDK .NET : C'est le kit de développement logiciel qui contient le runtime .NET, la CLI (Command Line Interface) .NET, et les outils nécessaires pour compiler et exécuter vos applications.
- Téléchargez la dernière version stable du SDK .NET depuis le site officiel : https://dotnet.microsoft.com/download
Un éditeur de code ou un IDE :
- Visual Studio Code (VS Code) : Un éditeur de code léger mais puissant, open-source et multiplateforme. Il est très populaire pour le développement .NET Core grâce à l'extension C#. C'est ce que nous utiliserons pour nos exemples.
- Visual Studio (Community Edition) : Un IDE complet et puissant pour Windows (et une version pour macOS). Il est plus lourd mais offre un ensemble d'outils plus riche pour des projets de grande envergure.

Vérification de l'installation du SDK .NET :

Ouvrez un terminal ou une invite de commande et tapez :

dotnet --version

Vous devriez voir un numéro de version (ex: 7.0.400 ou 8.0.100). Si c'est le cas, vous êtes prêt !

6. Création de Votre Première API REST avec ASP.NET Core

Nous allons créer une API simple pour gérer une collection de produits.

6.1. Initialisation du projet

Ouvrez votre terminal (ou l'invite de commande) et naviguez vers le répertoire où vous souhaitez créer votre projet. Ensuite, utilisez la CLI .NET pour créer un nouveau projet d'API web :

dotnet new webapi -n MyProductApi -o MyProductApi

dotnet new webapi : Crée un nouveau projet basé sur le modèle "Web API".
-n MyProductApi : Définit le nom du projet comme MyProductApi.
-o MyProductApi : Crée un nouveau dossier nommé MyProductApi et y place le projet.

Après l'exécution de cette commande, accédez au dossier du projet :

cd MyProductApi

Vous pouvez maintenant ouvrir ce dossier avec Visual Studio Code :

code .

6.2. Structure d'un projet Web API ASP.NET Core

Lorsque vous ouvrez le projet, vous verrez une structure de fichiers similaire à celle-ci :

MyProductApi/
├── Controllers/
│   └── WeatherForecastController.cs  <-- (Nous allons le supprimer ou le remplacer)
├── Properties/
│   └── launchSettings.json
├── appsettings.Development.json
├── appsettings.json
├── Program.cs
├── MyProductApi.csproj
├── .gitignore
└── ...

MyProductApi.csproj : Le fichier projet C# qui définit les dépendances et les configurations du projet.
Program.cs : Le point d'entrée de votre application. Dans les versions modernes d'ASP.NET Core (depuis .NET 6), il contient la configuration de l'hôte, les services, et le middleware (souvent appelé "Minimal APIs" pour des APIs plus simples, mais il peut aussi configurer des contrôleurs traditionnels).
Controllers/ : Ce dossier contiendra vos classes de contrôleurs, qui sont responsables de la gestion des requêtes HTTP.
appsettings.json : Fichier de configuration de l'application.

6.3. Comprendre le `Program.cs`

Le fichier Program.cs est le cœur de votre application. Il configure le pipeline de requêtes HTTP et l'injection de dépendances.

// 1. Crée un "builder" d'application web, qui est utilisé pour configurer les services et le pipeline de requêtes.
var builder = WebApplication.CreateBuilder(args);

// 2. Ajout des services au conteneur d'injection de dépendances.
// Configure les services nécessaires pour les contrôleurs MVC/API, l'OpenAPI (Swagger) pour la documentation de l'API.
builder.Services.AddControllers(); // Ajoute les services pour les contrôleurs (nécessaire pour les API traditionnelles)
builder.Services.AddEndpointsApiExplorer(); // Permet la découverte des endpoints pour Swagger
builder.Services.AddSwaggerGen(); // Génère la documentation Swagger/OpenAPI

// 3. Construit l'application web à partir du builder.
var app = builder.Build();

// 4. Configure le pipeline de requêtes HTTP.
// Ces lignes définissent l'ordre dans lequel les middlewares traitent les requêtes.

// En mode développement, on utilise Swagger pour la documentation interactive de l'API.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger(); // Active le middleware Swagger
    app.UseSwaggerUI(); // Active l'interface utilisateur Swagger
}

app.UseHttpsRedirection(); // Redirige les requêtes HTTP vers HTTPS

app.UseAuthorization(); // Active l'autorisation (si configurée)

app.MapControllers(); // Mappe les requêtes entrantes aux méthodes des contrôleurs.
                      // C'est ici que le routage vers vos API se produit.

// 5. Démarre l'application.
app.Run();

builder.Services.AddControllers(); : Enregistre les services nécessaires pour les contrôleurs, permettant à ASP.NET Core de découvrir et d'instancier vos contrôleurs.
builder.Services.AddSwaggerGen(); et app.UseSwagger(); app.UseSwaggerUI(); : Ces lignes activent Swagger/OpenAPI, un outil fantastique pour documenter et tester vos APIs directement depuis le navigateur.
app.MapControllers(); : Cette ligne est essentielle. Elle dit à ASP.NET Core de mapper les requêtes HTTP entrantes aux méthodes d'action appropriées dans vos contrôleurs.

6.4. Création d'un Modèle de Données (DTO)

Un DTO (Data Transfer Object) est une classe C# qui représente la structure des données que votre API va envoyer ou recevoir. Créons un modèle simple pour nos produits.

Créez un nouveau dossier nommé Models à la racine de votre projet, et à l'intérieur, créez un fichier Product.cs :

// Models/Product.cs
namespace MyProductApi.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; } = string.Empty; // Initialisation pour éviter les nulls
        public decimal Price { get; set; }
        public string Description { get; set; } = string.Empty;
    }
}

Chaque propriété (Id, Name, Price, Description) correspondra à un champ dans le JSON que nous échangerons.
L'initialisation des string avec string.Empty est une bonne pratique pour éviter les avertissements de nullabilité en C# moderne.

6.5. Création d'un Contrôleur

Les contrôleurs sont des classes qui gèrent les requêtes HTTP spécifiques. Ils contiennent des "actions" (méthodes) qui répondent aux requêtes HTTP entrantes (GET, POST, etc.).

Commencez par supprimer le fichier WeatherForecastController.cs du dossier Controllers (ou renommez-le et videz son contenu).

Ensuite, créez un nouveau fichier ProductsController.cs dans le dossier Controllers :

// Controllers/ProductsController.cs
using Microsoft.AspNetCore.Mvc;
using MyProductApi.Models; // N'oubliez pas d'importer votre modèle !

namespace MyProductApi.Controllers
{
    [ApiController] // Indique que cette classe est un contrôleur d'API
    [Route("api/[controller]")] // Définit le chemin de base pour ce contrôleur (ex: /api/Products)
    public class ProductsController : ControllerBase
    {
        // Une liste statique pour simuler une base de données en mémoire.
        // En production, vous utiliseriez une vraie base de données.
        private static List<Product> _products = new List<Product>
        {
            new Product { Id = 1, Name = "Laptop", Price = 1200.00m, Description = "Puissant ordinateur portable" },
            new Product { Id = 2, Name = "Mouse", Price = 25.00m, Description = "Souris optique sans fil" },
            new Product { Id = 3, Name = "Keyboard", Price = 75.50m, Description = "Clavier mécanique rétroéclairé" }
        };
        private static int _nextId = 4; // Pour générer de nouveaux IDs

        // GET: api/Products
        [HttpGet] // Indique que cette méthode répond aux requêtes GET
        public ActionResult<IEnumerable<Product>> GetProducts()
        {
            return Ok(_products); // Retourne la liste des produits avec un statut 200 OK
        }

        // GET: api/Products/{id}
        [HttpGet("{id}")] // Indique que cette méthode répond aux requêtes GET avec un paramètre d'ID dans l'URL
        public ActionResult<Product> GetProduct(int id)
        {
            var product = _products.FirstOrDefault(p => p.Id == id);

            if (product == null)
            {
                return NotFound(); // Retourne un statut 404 Not Found si le produit n'est pas trouvé
            }

            return Ok(product); // Retourne le produit trouvé avec un statut 200 OK
        }

        // POST: api/Products
        [HttpPost] // Indique que cette méthode répond aux requêtes POST
        public ActionResult<Product> PostProduct([FromBody] Product product) // [FromBody] mappe les données du corps de la requête au modèle Product
        {
            if (product == null)
            {
                return BadRequest("Le produit ne peut pas être null."); // Retourne 400 Bad Request
            }

            // Génère un nouvel ID et ajoute le produit à la liste
            product.Id = _nextId++;
            _products.Add(product);

            // Retourne un statut 201 CreatedAtAction avec le produit créé et l'URL pour le récupérer
            return CreatedAtAction(nameof(GetProduct), new { id = product.Id }, product);
        }

        // PUT: api/Products/{id}
        [HttpPut("{id}")] // Indique que cette méthode répond aux requêtes PUT avec un paramètre d'ID
        public IActionResult PutProduct(int id, [FromBody] Product product)
        {
            if (id != product.Id)
            {
                return BadRequest("L'ID dans l'URL ne correspond pas à l'ID du produit.");
            }

            var existingProduct = _products.FirstOrDefault(p => p.Id == id);
            if (existingProduct == null)
            {
                return NotFound();
            }

            // Met à jour les propriétés du produit existant
            existingProduct.Name = product.Name;
            existingProduct.Price = product.Price;
            existingProduct.Description = product.Description;

            return NoContent(); // Retourne un statut 204 No Content (pas de contenu à retourner pour une mise à jour réussie)
        }

        // DELETE: api/Products/{id}
        [HttpDelete("{id}")] // Indique que cette méthode répond aux requêtes DELETE avec un paramètre d'ID
        public IActionResult DeleteProduct(int id)
        {
            var productToRemove = _products.FirstOrDefault(p => p.Id == id);
            if (productToRemove == null)
            {
                return NotFound();
            }

            _products.Remove(productToRemove);

            return NoContent(); // Retourne un statut 204 No Content
        }
    }
}

Explication des éléments clés du contrôleur :

[ApiController] : Cet attribut est crucial. Il indique à ASP.NET Core que la classe est un contrôleur d'API et active des comportements spécifiques, tels que l'inférence de la source des paramètres (par exemple, d'où viennent les données, comme [FromBody]), la validation automatique des modèles, et des réponses d'erreur automatiques pour les validations.
[Route("api/[controller]")] : Cet attribut définit le modèle de route pour toutes les actions dans ce contrôleur. [controller] est un jeton de remplacement qui sera remplacé par le nom du contrôleur sans le suffixe "Controller" (donc Products pour ProductsController). Ainsi, toutes les requêtes commenceront par /api/Products.
public class ProductsController : ControllerBase : Tous les contrôleurs d'API doivent hériter de ControllerBase. Cette classe fournit l'accès à des fonctionnalités importantes comme les méthodes d'aide pour retourner des codes de statut HTTP (Ok(), NotFound(), CreatedAtAction(), NoContent(), BadRequest()).
[HttpGet], [HttpPost], [HttpPut], [HttpDelete] : Ces attributs (HttpVerbs) indiquent quel type de requête HTTP la méthode d'action doit gérer.
[HttpGet("{id}")] : Le {id} entre accolades est un paramètre de route. Il capture une valeur de l'URL et la mappe à l'argument id de la méthode.
ActionResult<T> ou IActionResult :
- ActionResult<T> : Retourne un type spécifique (ex: Product) tout en permettant de retourner également des IActionResult (comme NotFound()). Le framework s'occupe de la sérialisation de T en JSON.
- IActionResult : Interface utilisée lorsque l'action peut retourner différents types de résultats d'action HTTP (par exemple, Ok, NotFound, BadRequest).
[FromBody] : Indique à ASP.NET Core de lier les données du corps de la requête HTTP (généralement JSON) à l'objet Product.

6.6. Exécuter et Tester Votre API

Maintenant que votre API est prête, il est temps de la tester !

1. Démarrer l'application :

Dans votre terminal, assurez-vous d'être dans le dossier MyProductApi et exécutez :

dotnet run

Le terminal affichera des messages indiquant que l'application a démarré et écoute sur certaines URLs, généralement https://localhost:70XX (le numéro de port peut varier).

2. Tester avec Swagger UI :

Ouvrez votre navigateur et naviguez vers l'URL HTTPS affichée dans le terminal, puis ajoutez /swagger à la fin. Par exemple : https://localhost:70XX/swagger.

Vous devriez voir l'interface Swagger UI, qui liste toutes les endpoints de votre API (/api/Products).

GET /api/Products :
- Cliquez sur la ligne GET /api/Products.
- Cliquez sur le bouton "Try it out".
- Cliquez sur le bouton "Execute".
- Vous devriez voir la liste des produits que nous avons initialisés dans le contrôleur.
GET /api/Products/{id} :
- Cliquez sur la ligne GET /api/Products/{id}.
- Cliquez sur "Try it out".
- Dans le champ id, entrez 1.
- Cliquez sur "Execute". Vous devriez voir le produit avec l'ID 1 (Laptop).
POST /api/Products :
- Cliquez sur la ligne POST /api/Products.
- Cliquez sur "Try it out".
- Le "Request body" est pré-rempli avec un exemple de structure JSON. Modifiez-le pour ajouter un nouveau produit :
```
{
  "name": "Webcam",
  "price": 50.00,
  "description": "Webcam HD pour visioconférences"
}
```
  (N'incluez pas l'Id, car il est généré par l'API).
- Cliquez sur "Execute". Vous devriez obtenir une réponse 201 Created avec le nouveau produit et son ID généré.

Vous pouvez tester les requêtes PUT et DELETE de la même manière.

Félicitations ! Vous avez créé et testé votre première API REST avec ASP.NET Core.

7. Bonnes Pratiques (Brefs)

Pour des applications plus complexes, voici quelques bonnes pratiques à considérer au-delà de cette introduction :

Séparation des préoccupations (n-tier/Clean Architecture) : Pour les applications réelles, évitez de mettre toute la logique dans le contrôleur. Séparez votre application en couches (par exemple, une couche de présentation/API, une couche de services/logique métier, une couche de données/accès à la base de données).
Utilisation d'une Base de Données : Au lieu d'une liste en mémoire, intégrez une vraie base de données (SQL Server, PostgreSQL, MySQL) avec un ORM comme Entity Framework Core.
Validation des données : Implémentez une validation robuste des entrées pour vous assurer que les données reçues sont valides avant de les traiter. ASP.NET Core offre des attributs de validation ([Required], [Range], etc.).
Gestion des erreurs : Implémentez une gestion centralisée des erreurs pour renvoyer des réponses cohérentes et informatives en cas de problème.
Authentification et Autorisation : Sécurisez votre API en implémentant des mécanismes d'authentification (ex: JWT Bearer Token) et d'autorisation pour contrôler l'accès aux ressources.
Logging : Enregistrez les événements importants et les erreurs pour le débogage et le suivi en production.
Tests Unitaires et d'Intégration : Écrivez des tests pour garantir la fiabilité de votre code.

8. Conclusion et Résumé

Dans cette leçon, nous avons effectué une plongée essentielle dans le monde d'ASP.NET Core et de la création d'APIs REST.

Nous avons appris que :

ASP.NET Core est un framework multiplateforme, performant et modulaire idéal pour le développement backend.
Les APIs RESTful s'appuient sur des concepts clairs de ressources et de verbes HTTP standard (GET, POST, PUT, DELETE).
La CLI .NET est un outil puissant pour initialiser et gérer les projets.
Les contrôleurs (Controllers) sont le cœur de votre API, mappant les requêtes HTTP à des actions C#.
Swagger/OpenAPI est un outil indispensable pour documenter et tester interactivement vos APIs.

Vous avez maintenant les bases solides pour commencer à construire des services backend robustes. C'est la première étape d'un voyage passionnant vers le développement backend. Dans les prochaines leçons, nous explorerons des sujets plus avancés, comme l'intégration de bases de données, l'authentification, la gestion d'erreurs avancée et les principes de microservices.

Continuez à explorer, à coder et à poser des questions ! Le chemin vers l'expertise est pavé de pratique.