Apprendre à créer un service WebAPI et à l'utiliser via plusieurs technologies

En se basant sur le travail de Roy Fielding, Leonard Richardson a établi un modèle de maturité des services web REST appelé Richardson Maturity Model (RMM). Ce modèle est composé de quatre niveaux permettant d'évaluer une API par rapport aux contraintes REST :

• Niveau 0 : le protocole HTTP est utilisé uniquement à des fins de transport du message (cf. SOAP par exemple). L'ensemble des données transitent par un seul et unique point d'entrée.
• Niveau 1 : introduction de la notion de ressources. Il y a donc désormais plusieurs endpoint (URI) par ressource.
• Niveau 2 : apparition de la notion d'action et d'état, ce qui correspond aux verbes (GET, POST, PUT, DELETE…) et aux codes (200, 404, 500…) en HTTP.
• Niveau 3 : ultime et dernière notion de REST : HATEOAS (Hypertext As The Engine Of Application State). Cela permet de rendre l'API « autodocumentée », c'est-à-dire que l'on peut passer d'une action à une autre via des URL transmises par l'API dans les réponses. Pour illustrer cela, prenons le cas d'un service web de gestion de bibliothèque. Si l'on demande un livre spécifique, l'API va nous retourner un flux JSON avec les données de ce livre ainsi que des liens vers la page de l'auteur, des livres liés (du même genre ou du même auteur par exemple) ou encore un lien permettant d'ajouter le livre à son panier pour l'acheter. Tout cela permet d'enrichir énormément notre API et d'offrir à l'utilisateur des interactions supplémentaires.

Une API est donc RESTful si elle atteint le niveau 3 du modèle RMM. Dans le cas contraire, contentez-vous de parler d'API ou d'API HTTP…

II-A-1. Bonnes pratiques et règles de nommage▲

II-A-2. Versioning▲

Pour mettre en pratique le contenu des articles, notre projet « fil rouge » sera un gestionnaire de bandes dessinées. Nous allons commencer aujourd'hui par la création du modèle via Entity Framework Core ainsi que le développement de nos services web. Ce projet sera enrichi au fur et à mesure des articles (avec un site web de consultation, un site web d'administration et une application mobile).

Voilà la liste des fonctionnalités que je souhaiterais implémenter. Tout ne sera pas forcément intégré dès le début, mais j'enrichirai tout cela au fur et à mesure de l'écriture des articles et du temps que j'ai à ma disposition.

• Afficher de manière simple et sexy la liste de mes BD (compatible avec un affichage smartphone).
• Gérer les fiches d'informations des BD (nom, image de couverture, auteur, collection, éditeur, date de publication, genre…).
• Lier un fichier (PDF/cbz/cbr) à une BD.
• Pouvoir gérer une liste de lectures et un statut lu/non lu.
• Pouvoir afficher des statistiques sur ma bibliothèque (nombre total de BD, nombre total de BD lues, nombre total par genre, par collection…) via des chiffres et des diagrammes.
• Et sûrement plein d'autres choses… !

Pour bien commencer, je vais créer la solution « ComicsManager » qui contiendra trois projets que je vais rapidement détailler.

III-B-1. ComicsManager.API▲

III-B-2. ComicsManager.Common▲

III-B-3. ComicsManager.Model▲

Avec Entity Framework Core, nous ne disposons plus du type de fichier EDMX et donc plus de possibilités pour modéliser graphiquement nos entités. De ce fait, le passage par du Code-First est désormais obligatoire. Pour ma part, et même s'il est nécessaire de changer ses habitudes, je trouve que l'on y gagne clairement au change. Le format XML de l'EDMX commençait à dater et la fiabilité n'était pas toujours au rendez-vous (notamment dans le cadre d'une utilisation avec une gestion de code source).

Pour commencer, je vais partir avec quatre entités, que l'on pourra enrichir si nécessaire par la suite en fonction des besoins.

La 1re étape est donc de créer nos classes C# qui représenteront chacune une entité de notre modèle. Je vais prendre un exemple avec la classe Comics :

public class Comic : BaseEntity
{
    [Required]
    public string Title { get; set; }

    public int Cycle { get; set; }

    public string Collection { get; set; }

    public int Note { get; set; }

    public string ISBN { get; set; }

    public DateTime PublicationDate { get; set; }

    public string Couverture { get; set; }

    public Author Scenariste { get; set; }

    public Author Dessinateur { get; set; }    

    public Editor Editeur { get; set; } 
}

L'avantage de ce mode de création est de pouvoir conserver du code C# sur toute la chaine. Il est possible de spécifier des contraintes sur chacune des propriétés, via des attributs. Par exemple, pour la propriété Title, l'attribut [Required] spécifie que la propriété est obligatoire, ce qui se traduit par une colonne Not Null en base de données.

En vrac, je peux citer quelques attributs importants :

• Table : à spécifier sur une classe, permet de dire sur quelle table la classe sera mappée ;
• Column : même chose que pour la table, mais pour une colonne ;
• ForeignKey : permet de spécifier la propriété utilisée comme clé étrangère dans une relation ;

• DatabaseGenerated : spécifie le type de génération automatique de la valeur

  • Computed : génère une nouvelle valeur lors de la création (INSERT) ET de la mise à jour (UPDATE) d'une entité,
  • Identity : génère une nouvelle valeur lors de la création de l'entité,
  • None : désactive la génération automatique :
• NotMapped : indique que la propriété est exclue du mapping avec la base de données ;
• InverseProperty : permet de définir la propriété « inverse » d'une clé étrangère. Je vais illustrer ça avec un rapide exemple :

public class Comic 
{
    public Guid Id { get; set; }

    [Required]
    public string Title { get; set; }

    public Author Scenariste { get; set; }
}

public class Author 
{
    public Guid Id { get; set; }
    
    public string Name { get; set; }

    [InverseProperty("Scenariste")]
    public List<Comic> Comics { get; set; }
}

• MaxLength : taille maximale pour un champ de type string ou array ;
• Key : permet de spécifier une ou plusieurs clé(s) primaire(s) ; par défaut, une colonne ayant pour nom « Id » est automatiquement reconnue en tant que clé primaire (ce qui est le cas dans mon exemple).

Chacune de mes entités hérite d'une classe BaseEntity qui contient les propriétés techniques communes :

/// <summary>
/// Propriétés communes à l'ensemble des entités
/// </summary>
public class BaseEntity
{
    /// <summary>
    /// Identifiant de l'entité
    /// </summary>
    public Guid Id { get; set; }

    /// <summary>
    /// Date de création de l'entité (pour le tracking)
    /// </summary>
    public DateTime CreatedOn { get; set; }

    /// <summary>
    /// Date de modification de l'entité (pour le tracking)
    /// </summary>
    public DateTime ModifiedOn { get; set; }
}

Pour gérer la valorisation de ces trois propriétés, j'ai choisi de surcharger les méthodes SaveChanges() et SaveChangesAsync() du DbContext.

public override int SaveChanges()
{
    AddTimestamps();
    return base.SaveChanges();
}

public override Task<int> SaveChangesAsync(CancellationToken cancellationToken = default(CancellationToken))
{
    AddTimestamps();
    return base.SaveChangesAsync(cancellationToken);
}

/// <summary>
/// Gestion du remplissage automatique des colonnes Id/CreatedOn/ModifiedOn
/// </summary>
private void AddTimestamps()
{
    var entities = ChangeTracker.Entries().Where(x => x.Entity is BaseEntity && (x.State == EntityState.Added || x.State == EntityState.Modified));
    foreach (var entity in entities)
    {
        var now = DateTime.Now;

        if (entity.State == EntityState.Added)
        {
            ((BaseEntity)entity.Entity).Id = Guid.NewGuid();
            ((BaseEntity)entity.Entity).CreatedOn = now;
        }

        ((BaseEntity)entity.Entity).ModifiedOn = now;
    }
}

Dans tout projet, il est rare de conserver le même modèle du début jusqu'à la fin des développements. Il arrive d'avoir oublié des points ou encore de voir évoluer le besoin (suite à une demande du client par exemple). Jusqu'à maintenant, j'utilisais le plus souvent un projet SQL Server Database ( cf. mon article à ce sujet). Avec EF Core, on gagne un nouvel outil pour gérer les évolutions de notre modèle : les migrations.

III-D-1. Créer et supprimer une migration▲

Derrière ce mot barbare, se cache un concept extrêmement pratique permettant de gagner beaucoup de temps lors de la création d'une application. Dans les grandes lignes, Visual Studio va analyser votre modèle de données et va générer les vues (pour notre exemple, nous ne sommes pas concernés par cette partie, notre API ne comporte pas de vues, mais retourne du JSON) et les contrôleurs nécessaires pour réaliser les actions CRUD standards (Create/Read/Update/Delete). Par exemple, pour le cas d'une création, le formulaire avec l'ensemble des champs permettant de créer notre entité sera déjà existant, accompagné des mécanismes de validation et d'insertion en base. Il ne restera plus qu'à apporter les personnalisations nécessaires à notre cas d'utilisation. Cela évite l'écriture de code répétitif !

Dans le cas d'une WebAPI, le scaffolding fonctionne sur le même principe, mais sans générer de vues HTML. La classe générée va proposer les méthodes suivantes (pour l'entité Editor) :

[Produces("application/json")]
[Route("api/Editors")]
public class EditorsController : BaseController
{
    public EditorsController(ComicsManagerContext context)
        : base(context)
    { }

    // GET: api/Editors
    [HttpGet]
    public IEnumerable<Editor> GetEditors() ...    

    // GET: api/Editors/5
    [HttpGet("{id}")]
    public async Task<IActionResult> GetEditor([FromRoute] Guid id) ...

    // PUT: api/Editors/5
    [HttpPut("{id}")]
    public async Task<IActionResult> PutEditor([FromRoute] Guid id, [FromBody] Editor editor) ...

    // POST: api/Editors
    [HttpPost]
    public async Task<IActionResult> PostEditor([FromBody] Editor editor) ...
    // DELETE: api/Editors/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteEditor([FromRoute] Guid id) ...

    private bool EditorExists(Guid id) ...
}

En quelques clics, tout est donc prêt pour avoir une API fonctionnelle permettant de réaliser les principales opérations de base sur notre entité « Editor » !

Techniquement, le scaffolding repose sur ce que l'on appelle des templates T4. C'est un mécanisme de génération de code propre à Microsoft et qui existe depuis Visual Studio 2005 (il y a quand même quelques ajustements avec l'arrivée de .NET Core) ! On peut trouver les templates de base à cet emplacement : C:\Users{username}.nuget\packages\microsoft.visualstudio.web.codegenerators.mvc\1.0.1\Templates. C'est une très bonne base pour créer ses propres templates. Évidemment, si vous ne souhaitez pas créer les vôtres, des développeurs se sont déjà penchés sur le sujet et il existe plusieurs packages NuGet proposant des templates supplémentaires.

Les méthodes d'un contrôleur peuvent retourner deux types de résultats.

• Un objet, qui sera donc sérialisé en JSON. Par exemple, pour la méthode GetEditors(), on retourne un IEnumerable qui sera donc directement sérialisé en JSON dans le corps de la réponse avec un code 200.

• Un IActionResult, plus générique, qui peut représenter pas mal de choses :

  • des erreurs :

    • NotFound() qui correspondra à un code 404,
    • BadRequest(),
    • Forbid() :

  • un succès :

    • ObjectResponse(), avec un objet, qui reviendra à retourner directement l'objet avec un code 200,
    • File(),
    • Redirect() ;
  • la classe ControllerBase de Microsoft.AspNetCore.Mvc.Core contient de nombreuses autres méthodes de retour.

L'avantage du scaffolding, c'est que les principes de base sont déjà implémentés : vérification de la validité du modèle, conformité des paramètres, vérification de l'existence en base… Il ne reste plus qu'à implémenter les éléments spécifiques aux besoins métier de notre application.

Sur le même principe que ma classe BaseEntity, j'ai tendance à toujours faire hériter mes contrôleurs d'une classe BaseController. Cela me permet de centraliser les éléments communs, comme le DbContext, la configuration, le logger… Les services sont injectés dans le constructeur du contrôleur et sont directement passés au constructeur de la classe parente (nous verrons cela plus en détail dans le chapitre dédié à l'injection de dépendances). Cette classe permet aussi de mettre des méthodes communes à disposition de l'ensemble des contrôleurs.

L'inversion de contrôle est un concept architectural permettant, notamment, de remplacer et de surcharger les comportements natifs du framework .NET. C'est aussi un formidable moyen architectural pour rendre une application robuste et pour faciliter le découpage des responsabilités en modules. Son implémentation la plus connue est l'injection de dépendances et, dans .NET Core, ce mécanisme est désormais intégré de manière native. Le framework s'appuie d'ailleurs énormément dessus pour faciliter sa modularité et sa flexibilité. Il existe aussi des conteneurs IoC tiers, comme Unity, Ninject ou StructureMap. Dans la plupart des cas, celui de Microsoft va suffire, mais dans le cas où vous avez besoin de fonctionnalités avancées ou que vous êtes encore en .NET classique, cela peut être utile.

Un conteneur IoC joue essentiellement deux rôles:

• un rôle de catalogue, contenant l'ensemble des types abstraits (interfaces) et leur implémentation (un dictionnaire ). Grâce à cela, le conteneur est capable de savoir, pour chaque type abstrait, l'implémentation correspondante. Le remplissage de ce catalogue est à la charge du développeur, et dans le cas de .NET Core, il se réalise dans la méthode ConfigureServices() de la classe Startup. Le conteneur s'appelle IServiceProvider ;
• un rôle de chef d'orchestre, pour instancier automatiquement les dépendances demandées par chaque classe avec le bon scope (il en existe quatre, dont j'ai déjà parlé dans mon article précédent : Instance, Transient, Singleton et Scoped). Pour demander une dépendance, il suffit de l'ajouter dans le constructeur de sa classe. Il suffira ensuite de l'enregistrer pour qu'elle soit disponible.

En .NET Core, l'injection de dépendances est beaucoup utilisée pour ajouter des nouvelles fonctionnalités à la plateforme (AddMVC(), AddIdentity(), AddDbContext()…). En coulisse, ces méthodes sont simplement des raccourcis pour enregistrer les différents composants nécessaires. Décompilons par exemple la DLL Microsoft.AspNetCore.Mvc.dll et regardons le code de la méthode AddMvc :

/// <summary>
/// Adds MVC services to the specified <see cref="T:Microsoft.Extensions.DependencyInjection.IServiceCollection" />.
/// </summary>
/// <param name="services">The <see cref="T:Microsoft.Extensions.DependencyInjection.IServiceCollection" /> to add services to.</param>
/// <returns>An <see cref="T:Microsoft.Extensions.DependencyInjection.IMvcBuilder" /> that can be used to further configure the MVC services.</returns>
public static IMvcBuilder AddMvc(this IServiceCollection services)
{
    if (services == null)
    {
        throw new ArgumentNullException("services");
    }
    
    IMvcCoreBuilder mvcCoreBuilder = MvcCoreServiceCollectionExtensions.AddMvcCore(services);
    MvcApiExplorerMvcCoreBuilderExtensions.AddApiExplorer(mvcCoreBuilder);
    MvcCoreMvcCoreBuilderExtensions.AddAuthorization(mvcCoreBuilder);
    MvcServiceCollectionExtensions.AddDefaultFrameworkParts(mvcCoreBuilder.get_PartManager());
    MvcCoreMvcCoreBuilderExtensions.AddFormatterMappings(mvcCoreBuilder);
    MvcViewFeaturesMvcCoreBuilderExtensions.AddViews(mvcCoreBuilder);
    MvcRazorMvcCoreBuilderExtensions.AddRazorViewEngine(mvcCoreBuilder);
    MvcRazorPagesMvcCoreBuilderExtensions.AddRazorPages(mvcCoreBuilder);
    TagHelperServicesExtensions.AddCacheTagHelper(mvcCoreBuilder);
    MvcDataAnnotationsMvcCoreBuilderExtensions.AddDataAnnotations(mvcCoreBuilder);
    MvcJsonMvcCoreBuilderExtensions.AddJsonFormatters(mvcCoreBuilder);
    MvcCorsMvcCoreBuilderExtensions.AddCors(mvcCoreBuilder);
    return new MvcBuilder(mvcCoreBuilder.get_Services(), mvcCoreBuilder.get_PartManager());
}

On note que le fonctionnement est identique à ce que nous faisons dans la méthode Startup : les différents services et composants nécessaires au bon fonctionnement de MVC sont ajoutés les uns après les autres via des méthodes Addxxx(…).

Il est aussi possible d'injecter une dépendance uniquement sur une action (via [FromServices] devant le paramètre) ou même dans une vue (via @inject).

L'un des gros avantages de l'injection de dépendances est de faciliter la mise en place des tests unitaires. En effet, passer par des interfaces implique que le consommateur de cette dernière n'a plus à se préoccuper du fonctionnement de l'interface, mais uniquement de sa signature. Il est donc très simple d'utiliser plusieurs implémentations différentes à partir du moment ou elles respectent la même interface. Par exemple, en production notre service d'accès aux données va utiliser une implémentation vers SQL Server. Dans le cadre de nos tests, on peut avoir envie de lui fournir une implémentation qui simule l'accès aux données à partir de « fausses données ». De même, si un jour on souhaite changer de fournisseur de données (passage à SQLite), il suffira de changer l'implémentation (ce n'est pas toujours aussi simple malheureusement !).

Pour terminer sur cette partie, voilà le contenu de la méthode ConfigureServices() de ma classe Startup :

services.AddLogging();
services.AddMemoryCache();

services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

// Authentication
services.AddIdentity<ApplicationUser, IdentityRole>()
    .AddEntityFrameworkStores<ApplicationDbContext>()
    .AddDefaultTokenProviders()
    .AddPasswordValidator<UsernameAsPasswordValidator>();

// Add email service
services.AddTransient<IEmailSender, EmailSender>();

// Service de messages
services.AddTransient<IMessageManager, MessageManager>();

// Localization
services.AddLocalization(options => options.ResourcesPath = "Resources");

services.AddMvc(config =>
{
    // Global exceptions handler
    config.Filters.Add(typeof(GlobalExceptionsFilter));
});

// Paging
services.AddPaging();

Dans une application .NET Core, la gestion de la configuration est un peu différente de ce à quoi on avait l'habitude jusqu'à maintenant. Désormais, tout passe par un fichier appsettings.json (c'est le nommage standard, il est évidemment possible de mettre ce que l'on veut) contenant l'ensemble des clés de configuration :

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=MyDatabase;Trusted_Connection=True;MultipleActiveResultSets=true"
  },
  "AppSettings": {    
    "DocumentsDirectory": "C:\\Temp\Documents",
    "CacheDurationInHours": 24
  }  
}

Pour charger la configuration, il suffit d'utiliser le code suivant dans le constructeur de notre classe Startup. C'est à ce moment que l'on peut personnaliser le fichier de configuration en fonction du nom de la machine ou du type d'environnement (développement, préprod, prod…). C'est très pratique lors de la phase de développement pour permettre à chaque développeur d'avoir sa propre configuration.

public Startup(IHostingEnvironment environment)
{
    Configuration = new ConfigurationBuilder()
        .AddJsonFile("appsettings.json")
        .AddJsonFile($"appsettings.{Environment.MachineName}.json", optional: true)
        .AddJsonFile($"appsettings.{environment.EnvironmentName}.json", optional: true)
        .AddEnvironmentVariables()
        .Build();
}

En termes d'utilisation, il est très simple de mapper notre configuration sur une classe C# (qui contiendra l'ensemble des paramètres spécifiés dans le fichier json), qui s'utilisera ensuite comme un service à injecter dans nos constructeurs :

// Mapping de la configuration
services.AddOptions();
services.Configure<AppSettings>(Configuration.GetSection("AppSettings"));

...

// Utilisation
public MyConstructor(IOptions<AppSettings> config)
{
    var cacheDuration = config.Value.CacheDurationInHours;
}

Par défaut, .NET Core fournit un service de log.

Pour l'activer, il suffit d'appeler services.AddLogging() dans la méthode ConfigureServices() de notre classe Startup puis de le configurer dans la méthode Configure(). Cela passe par l'interface ILoggerFactory qui propose plusieurs possibilités :

• AddConsole() : à utiliser en développement uniquement, peut causer des problèmes de performances ;
• AddDebug() : va permettre la mise en place de l'affichage des logs dans la console de développement de Visual Studio (le minimum dans une phase de développement). Il est évidemment possible de filtrer le niveau de log minimal requis (via LogLevel.Error par exemple en paramètre ou encore via une expression lambda qui proposera plus de souplesse) ;
• AddEventLog() : écrit dans l'EventViewer Windows (uniquement valable sous Windows du coup) ;
• AddAzureWebAppDiagnostic() : si vous êtes sous Azure, va écrire les logs dans un fichier texte hébergé dans le système de fichiers d'Azure.

Il est bien évidemment possible d'utiliser des packages tiers, comme Log4Net, NLog ou encore Serilog. Les trois s'installent sous la forme de packages NuGet. Ils permettent plus de souplesse dans la configuration et ouvrent la possibilité à des scénarios plus avancés. Je pense en particulier aux logs fichier ou aux logs en base de données, à la purge automatique, à la mise en place d'un format particulier pour les messages de log… Avec NLog par exemple, il est possible de configurer plusieurs cibles, avec pour chacune un filtrage sur la criticité du log. Par exemple, je souhaite tout logger en base de données, mais uniquement dans un fichier texte les logs de niveau erreur et critique. De plus, je voudrais envoyer un mail à une liste de diffusion en cas de log critique. Avec NLog, ce scénario est parfaitement possible.

Toute bonne application doit être équipée d'un bon système de gestion des erreurs. En plus de try/catcher les blocs sensibles de mes applications, une bonne habitude que j'ai prise est de créer un handler global d'exception pour centraliser la gestion des erreurs (et surtout de capter les erreurs oubliées :)) :

public class GlobalExceptionsFilter : IExceptionFilter
{
    private readonly ILogger _logger;

    public GlobalExceptionsFilter(
        ILoggerFactory logger)
    {
        if (logger == null)
        {
            throw new ArgumentNullException(nameof(logger));
        }

        _logger = logger.CreateLogger<GlobalExceptionsFilter>();
    }

    public void OnException(ExceptionContext context)
    {
        _logger.LogError(context.Exception, "");
    }
}

Il suffit ensuite d'ajouter notre filtre à la configuration du service MVC et le tour est joué :

services.AddMvc(config =>
{
   config.Filters.Add(typeof(GlobalExceptionsFilter));
});