Aller au contenu principal

23-2 Décortiquer le projet d'API

Le projet d'API est un projet serveur permettant de recevoir des requêtes HTTP et de retourner des réponses JSON.

Il suit une structure qui vous sera familière et à moins d'une amnésie générale, le tout devrait vous rappeler votre cours de Web III.

Prenons le temps de décortiquer le projet, soit les différents dossiers et fichiers.

Structure de dossiers et fichiers​

  1. Controllers: Ce dossier contient les contrôleurs de l'API, qui sont des classes C# dérivées de la classe ControllerBase. Les contrôleurs définissent les points de terminaison de l'API, gèrent les requêtes entrantes et renvoient les réponses aux clients. Chaque contrôleur gère généralement un ensemble d'actions liées à une ressource ou une entité spécifique.

  2. Program.cs: Ce fichier contient le point d'entrée de l'application .NET Core. Il configure et lance l'hôte Web, enregistre les services et charge les composants requis pour démarrer l'application.

  3. appsettings[.Development].json: Ce fichier contient les paramètres de configuration de l'application, tels que les chaînes de connexion, les clés API et d'autres paramètres spécifiques à l'environnement. Ces paramètres peuvent être lus et utilisés par les services et les contrôleurs de l'application.

Les principaux fichiers en détail​

Program.cs​

Ce fichier contient le point d'entrée de l'application .NET Core d'API. Il configure et lance l'hôte Web, enregistre les services et charge les composants requis pour démarrer l'application.

Snowfall.Web.Api/Program.cs
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Contrôleur WeatherForecastController​

Il s'agit d'un contrôleur avec des données de test créé automatiquement par Rider/.NET.

Nous allons éventuellement le supprimer, mais on peut s'en servir pour comprendre la structure de base d'un contrôleur d'API.

En-tête de classe​

Snowfall.Web.Api/Controllers/WeatherForecastController.cs
using Microsoft.AspNetCore.Mvc;

namespace Snowfall.Web.Api.Controllers;

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
info
  • [ApiController]: Ajoute des fonctionnalités au contrôleur afin d'améliorer et de simplifier l'expérience de développement pour des API de style REST. La validation des modèles sera implicite (ModelState.IsValid), donc pas besoin de gérer cet aspect comme dans le projet MVC. Une erreur 400 bad request sera automatiquement retournée dans le cas d'un modèle invalide. De plus, le binding entre les paramètres d'une fonction de contrôleur et le body de la requête HTTP se fera automatiquement.
  • [Route("[controller]")]: identique au projet MVC lorsqu'on défini une route de base pour un contrôleur. Ici la route a le nom du contrôleur comme nom par défaut (/weatherforecast).
  • ControllerBase: Classe de base de contrôleur, sans le support pour les View (une API retourne simplement du JSON ou un format de données similaire)

Action​

Snowfall.Web.Api/Controllers/WeatherForecastController.cs
[HttpGet(Name = "GetWeatherForecast")]
public IEnumerable<WeatherForecast> Get()
{
    return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
}
info

Le contrôleur définit ensuite une fonction (action) Get() associée à une requête HttpGet.

La requête répondra donc à une requête GET /weatherforecast.

Vous pouvez ignorer Name=, cela permet de donner un nom à une route pour y faire référence plus facilement ailleurs dans le code, mais cela n'a pas d'impact sur le comportement de la route ou de la fonction.

Un tableau est retourné et sera automatiquement converti en JSON. Nous verrons plus loin comment retourner des données de façon un peu plus avancée et avec différents codes de retour.

Utiliser Postman pour tester l'API​

Essayez d'utiliser Postman pour communiquer avec l'API et faire des tests. Par exemple, avec le projet d'API de démarré, on peut faire une requête GET à /WeatherForecast.

Imgur

On obtient le retour de la fonction Get() du contrôleur WeatherForecastController.