Comment utiliser la gestion des versions d'API dans ASP.NET Core

Lorsque vous développez des API, vous devez garder une chose à l'esprit: le changement est inévitable. Lorsque votre API a atteint un point où vous devez ajouter plus de responsabilités, vous devez envisager de versionner votre API. Par conséquent, vous aurez besoin d'une stratégie de gestion des versions.

Il existe plusieurs approches pour le contrôle de version des API, et chacune d'elles a ses avantages et ses inconvénients. Cet article abordera les défis de la gestion des versions d'API et comment vous pouvez travailler avec le package de gestion des versions ASP.NET Core MVC de Microsoft vers des API RESTful de version intégrées dans ASP.NET Core. Vous pouvez en savoir plus sur la gestion des versions de l'API Web dans mon article précédent ici. 

Créer un projet d'API ASP.NET Core 3.1

Tout d'abord, créons un projet ASP.NET Core dans Visual Studio. En supposant que Visual Studio 2019 est installé sur votre système, suivez les étapes décrites ci-dessous pour créer un nouveau projet ASP.NET Core dans Visual Studio.

  1. Lancez l'IDE de Visual Studio.
  2. Cliquez sur "Créer un nouveau projet".
  3. Dans la fenêtre «Créer un nouveau projet», sélectionnez «Application Web ASP.NET Core» dans la liste des modèles affichés.
  4. Cliquez sur Suivant.
  5. Dans la fenêtre «Configurer votre nouveau projet» ci-dessous, spécifiez le nom et l'emplacement du nouveau projet.
  6. Cliquez sur Créer.
  7. Dans la fenêtre «Créer une nouvelle application Web ASP.NET Core», sélectionnez .NET Core comme moteur d'exécution et ASP.NET Core 3.1 (ou version ultérieure) dans la liste déroulante en haut. J'utiliserai ASP.NET Core 3.1 ici.
  8. Sélectionnez «API» comme modèle de projet pour créer une nouvelle application API ASP.NET Core. 
  9. Assurez-vous que les cases à cocher «Activer le support Docker» et «Configurer pour HTTPS» ne sont pas cochées car nous n'utiliserons pas ces fonctionnalités ici.
  10. Assurez-vous que l'authentification est définie sur «Aucune authentification» car nous n'utiliserons pas non plus l'authentification.
  11. Cliquez sur Créer. 

Cela créera un nouveau projet d'API ASP.NET Core dans Visual Studio. Sélectionnez le dossier de solution Contrôleurs dans la fenêtre Explorateur de solutions et cliquez sur «Ajouter -> Contrôleur…» pour créer un nouveau contrôleur nommé DefaultController.

Remplacez le code source de la classe DefaultController par le code suivant.

    [Route ("api / [contrôleur]")]

    [ApiController]

    classe publique DefaultController: ControllerBase

    {

        chaîne [] auteurs = nouvelle chaîne []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        public IEnumerable Get ()

        {

            renvoyer les auteurs;

        }

    }

Nous utiliserons ce contrôleur dans les sections suivantes de cet article.

Pour implémenter la gestion des versions d'API dans ASP.NET Core, vous devez effectuer les opérations suivantes:

  1. Installez le package de gestion des versions ASP.NET Core MVC.
  2. Configurez la gestion des versions d'API dans la classe Startup.
  3. Annotez les contrôleurs et les actions avec les attributs appropriés.

Installer le package de gestion des versions ASP.NET Core MVC

ASP.NET Core prend en charge la gestion des versions d'API prête à l'emploi. Pour tirer parti de la gestion des versions d'API, il vous suffit d'installer le package Microsoft.AspNetCore.Mvc.Versioning à partir de NuGet. Vous pouvez le faire via le gestionnaire de packages NuGet dans l'IDE de Visual Studio 2019 ou en exécutant la commande suivante sur la console du gestionnaire de packages NuGet:

Package d'installation Microsoft.AspNetCore.Mvc.Versioning

Notez que si vous utilisez l'API Web ASP.NET, vous devez ajouter le package Microsoft.AspNet.WebApi.Versioning.

Configurer la gestion des versions d'API dans ASP.NET Core

Maintenant que le package nécessaire pour le contrôle de version de votre API a été installé dans votre projet, vous pouvez configurer le contrôle de version de l'API dans la méthode ConfigureServices de la classe Startup. L'extrait de code suivant illustre comment cela peut être réalisé.

public void ConfigureServices (services IServiceCollection)

{

  services.AddControllers ();

  services.AddApiVersioning ();

}

Lorsque vous effectuez une demande Get à votre API, l'erreur présentée dans la figure 1 vous sera présentée.

Pour résoudre cette erreur, vous pouvez spécifier la version par défaut lors de l'ajout des services de contrôle de version d'API au conteneur. Vous pouvez également utiliser une version par défaut si aucune version n'est spécifiée dans la demande. L'extrait de code suivant montre comment vous pouvez définir une version par défaut comme 1.0 à l'aide de la propriété AssumeDefaultVersionWhenUnspecified si les informations de version ne sont pas disponibles dans la demande.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = nouvelle ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

});

Notez comment la version majeure et la version mineure sont transmises au constructeur de la classe ApiVersion au moment de l'attribution de la version par défaut. La propriété AssumeDefaultVersionWhenUnspecified peut contenir des valeurs true ou false. S'il est vrai, la version par défaut spécifiée lors de la configuration du contrôle de version d'API sera utilisée si aucune information de version n'est disponible.

Le code source complet de la méthode ConfigureServices est donné ci-dessous pour votre référence.

public void ConfigureServices (services IServiceCollection)

{

    services.AddControllers ();

    services.AddApiVersioning (config =>

    {

         config.DefaultApiVersion = nouvelle ApiVersion (1, 0);

         config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

Comme vous n'avez spécifié aucune information de version, tous les points de terminaison auront la version 1.0 par défaut.

Signaler toutes les versions prises en charge de votre API

Vous souhaiterez peut-être informer les clients de l'API de toutes les versions prises en charge. Pour ce faire, vous devez tirer parti de la propriété ReportApiVersions comme indiqué dans l'extrait de code ci-dessous.

services.AddApiVersioning (config =>

{

  config.DefaultApiVersion = nouvelle ApiVersion (1, 0);

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = true;

});

Utiliser des versions dans le contrôleur et les méthodes d'action

Ajoutons maintenant quelques versions prises en charge à notre contrôleur en utilisant les attributs comme indiqué dans l'extrait de code ci-dessous.

    [Route ("api / [contrôleur]")]

    [ApiController]

    [ApiVersion ("1.0")]

    [ApiVersion ("1.1")]

    [ApiVersion ("2.0")]

    classe publique DefaultController: ControllerBase

    {

        chaîne [] auteurs = nouvelle chaîne []

        {"Joydip Kanjilal", "Steve Smith", "Anand John"};

        [HttpGet]

        public IEnumerable Get ()

        {

            renvoyer les auteurs;

        }

    }

Lorsque vous effectuez une requête Get à partir d'un client HTTP tel que Postman, voici comment les versions seront signalées.

Vous pouvez également signaler les versions obsolètes. Pour ce faire, vous devez transmettre un paramètre supplémentaire à la méthode ApiVersion comme indiqué dans l'extrait de code ci-dessous.

[ApiVersion ("1.0", obsolète = true)]

Mapper à une version spécifique d'une méthode d'action

Il existe un autre attribut important nommé MapToApiVersion. Vous pouvez l'utiliser pour mapper à une version spécifique d'une méthode d'action. L'extrait de code suivant montre comment cela peut être accompli.

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

chaîne publique Get (int id)

{

   renvoyer les auteurs [id];

}

Exemple complet de gestion des versions d'API dans ASP.NET Core

Voici le code source complet du DefaultController pour votre référence.

[Route ("api / [contrôleur]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

classe publique DefaultController: ControllerBase

{

  chaîne [] auteurs = nouvelle chaîne []

  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

  [HttpGet]

  public IEnumerable Get ()

  {

      renvoyer les auteurs;

  }

  [HttpGet ("{id}")]

  [MapToApiVersion ("2.0")]

  chaîne publique Get (int id)

  {

     renvoyer les auteurs [id];

  }

}

Stratégies de gestion des versions d'API dans ASP.NET Core

Il existe plusieurs façons dont vous pouvez versionner votre API dans ASP.NET Core. Dans cette section, nous allons explorer chacun d'eux.

Passer les informations de version en tant que paramètres QueryString

Dans ce cas, vous transmettez généralement les informations de version dans le cadre de la chaîne de requête, comme indiqué dans l'URL ci-dessous.

//localhost:25718/api/default?api-version=1.0

Passer les informations de version dans les en-têtes HTTP

Si vous devez transmettre des informations de version dans les en-têtes HTTP, vous devez les configurer dans la méthode ConfigureServices comme indiqué dans l'extrait de code ci-dessous.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = nouvelle ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

   config.ReportApiVersions = true;

   config.ApiVersionReader = nouveau HeaderApiVersionReader ("api-version");

});

Une fois que cela a été configuré, vous pouvez invoquer une méthode d'action relative à une version spécifique de l'API, comme illustré à la figure 3.

Passer les informations de version dans l'URL

Une autre méthode pour transmettre les informations de version consiste à transmettre les informations de version dans le cadre de l'itinéraire. C'est le moyen le plus simple de versionner votre API, mais il y a certaines mises en garde. Tout d'abord, si vous utilisez cette stratégie, vos clients devront mettre à jour l'URL chaque fois qu'une nouvelle version de l'API est publiée. Par conséquent, cette approche rompt un principe fondamental de REST qui stipule que l'URL d'une ressource particulière ne doit jamais changer.

Pour implémenter cette stratégie de contrôle de version, vous devez spécifier les informations de route dans votre contrôleur comme indiqué ci-dessous.

[Route ("api / v {version: apiVersion} / [controller]")]

La liste de codes suivante montre comment vous pouvez configurer cela dans votre classe de contrôleur.

[Route ("api / v {version: apiVersion} / [controller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

classe publique DefaultController: ControllerBase

    {

        chaîne [] auteurs = nouvelle chaîne []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        public IEnumerable Get ()

        {

            renvoyer les auteurs;

        }

        [HttpGet ("{id}")]

        [MapToApiVersion ("2.0")]

        chaîne publique Get (int id)

        {

            renvoyer les auteurs [id];

        }

    }

Voici comment appeler le HTTP par défaut pour obtenir la méthode de la classe DefaultController.

//localhost:25718/api/v1.0/default

Pour invoquer l'autre méthode HTTP GET, c'est-à-dire celle qui accepte un paramètre, spécifiez ce qui suit dans le navigateur Web ou dans un client HTTP tel que Postman.

//localhost:25718/api/v2.0/default/1

Déprécier une ou plusieurs versions de votre API

Supposons que vous disposiez de plusieurs versions de votre API mais que vous souhaitiez en désapprouver une ou plusieurs d'entre elles. Vous pouvez le faire facilement - il vous suffit de spécifier la propriété Deprecated de la classe ApiVersionAttribute sur true, comme indiqué dans l'extrait de code ci-dessous.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", obsolète = true)]

[ApiVersion ("2.0")]

classe publique DefaultController: ControllerBase

{

     // Code usuel

}

La gestion des versions d'API dans ASP.NET Core est désormais transparente grâce à l'introduction du package Microsoft.AspNetCore.Mvc.Versioning. Il existe plusieurs façons de mettre à jour votre API - il vous suffit de décider de la meilleure stratégie en fonction de vos besoins. Vous pouvez également utiliser plusieurs schémas de version pour votre API. Cela ajoute beaucoup de flexibilité puisque les clients peuvent choisir l'un des schémas de version pris en charge.

Comment faire plus dans ASP.NET Core:

  • Comment utiliser des objets de transfert de données dans ASP.NET Core 3.1
  • Comment gérer les erreurs 404 dans ASP.NET Core MVC
  • Comment utiliser l'injection de dépendances dans les filtres d'action dans ASP.NET Core 3.1
  • Comment utiliser le modèle d'options dans ASP.NET Core
  • Comment utiliser le routage de point de terminaison dans ASP.NET Core 3.0 MVC
  • Comment exporter des données vers Excel dans ASP.NET Core 3.0
  • Comment utiliser LoggerMessage dans ASP.NET Core 3.0
  • Comment envoyer des e-mails dans ASP.NET Core
  • Comment enregistrer des données sur SQL Server dans ASP.NET Core
  • Comment planifier des travaux à l'aide de Quartz.NET dans ASP.NET Core
  • Comment renvoyer des données à partir de l'API Web ASP.NET Core
  • Comment formater les données de réponse dans ASP.NET Core
  • Comment consommer une API Web ASP.NET Core à l'aide de RestSharp
  • Comment effectuer des opérations asynchrones à l'aide de Dapper
  • Comment utiliser les indicateurs de fonctionnalité dans ASP.NET Core
  • Comment utiliser l'attribut FromServices dans ASP.NET Core
  • Comment utiliser les cookies dans ASP.NET Core
  • Comment travailler avec des fichiers statiques dans ASP.NET Core
  • Comment utiliser le middleware de réécriture d'URL dans ASP.NET Core
  • Comment implémenter la limitation de débit dans ASP.NET Core
  • Comment utiliser Azure Application Insights dans ASP.NET Core
  • Utilisation des fonctionnalités NLog avancées dans ASP.NET Core
  • Comment gérer les erreurs dans l'API Web ASP.NET
  • Comment implémenter la gestion globale des exceptions dans ASP.NET Core MVC
  • Comment gérer les valeurs NULL dans ASP.NET Core MVC
  • Contrôle de version avancé dans l'API Web ASP.NET Core
  • Comment travailler avec les services de travail dans ASP.NET Core
  • Comment utiliser l'API de protection des données dans ASP.NET Core
  • Comment utiliser un middleware conditionnel dans ASP.NET Core
  • Comment travailler avec l'état de session dans ASP.NET Core
  • Comment écrire des contrôleurs efficaces dans ASP.NET Core