Premiers pas avec asp.net-web-api2

Quoi et pourquoi Asp.Net Web API2 ?

Quoi et pourquoi ?

L’API Web2 d’Asp.Net est la dernière version de l’API Web. C’est un moyen simple d’implémenter un service Web RESTful en utilisant toutes les qualités fournies par le framework Asp.Net. Une fois que vous aurez compris les principes de base de REST, une API Web Asp.net2 sera très facile à mettre en œuvre. Web API2 est construit sur le modèle de pipeline modulaire et enfichable d’Asp.Net. Cela signifie que lorsqu’un serveur hébergeant une API Web2 reçoit une requête, il passe d’abord par le pipeline de requêtes Asp.Nets. Cela vous permet d’ajouter facilement vos propres modules si vous trouvez que les fonctionnalités par défaut ne suffisent pas à vos besoins. Avec les récentes annonces sur “ASP.net vNext”, cela signifie également que vous pouvez potentiellement héberger votre API Web2 en dehors de Windows Server, ce qui ouvre toute une gamme de cas d’utilisation. Voir [ici][1] pour plus de détails.

Comment ça marche ?

Web API2 utilise les concepts de contrôleur et d’action de MVC. Les ressources sont mappées directement sur les contrôleurs ; vous auriez généralement un contrôleur différent pour chacune de vos principales entités de données (produit, personne, commande, etc.). Web API2 utilise le moteur de routage Asp.Net pour mapper les URL aux contrôleurs. En règle générale, les API sont conservées dans une route /api/ qui aide à distinguer les contrôleurs d’API des autres non-API sur le même site Web.

Les actions sont utilisées pour mapper des verbes HTTP spécifiques, par exemple, vous auriez généralement une action GET qui renvoie toutes les entités. Cette action répondrait à /api/Products (où ‘products’ est votre contrôleur) et ressemblerait à ceci :

 public IEnumerable<string> Get()
 {
     return new string[] { "value1", "value2" };
 }

Vous pouvez également avoir une action GET qui accepte un ID spécifique et renvoie une entité spécifique. Il répondrait à /api/Products/81 et ressemblerait à ceci :

public string Get(int id)
 {
    return "value";
 }

L’utilisation de l’API Web présente de nombreux avantages cachés que vous ne réalisez peut-être pas, mais qui vous épargnent en fait beaucoup de travail.

Web API2 fait partie du ‘One Asp.Net’

L’API Web2 fait partie de la famille “One Asp.Net”, ce qui signifie qu’elle prend en charge de manière native toutes les fonctionnalités partagées que vous pouvez actuellement utiliser avec MVC ou les formulaires Web, notamment (ce ne sont que quelques exemples) :

  • Cadre d’entité
  • Autorisation et identité
  • Echafaudage
  • Routage

Sérialisation et liaison de modèle

Web API2 est configuré par défaut pour fournir des réponses en XML ou JSON (JSON est la valeur par défaut). Cependant, en tant que développeur, vous n’avez pas besoin de faire de conversion ou d’analyse - vous renvoyez simplement un objet fortement typé et l’API Web2 le convertira en XML ou JSON et le renverra au client appelant, c’est un processus appelé négociation de contenu. Voici un exemple d’action GET qui renvoie un objet Product fortement typé.

 public Product GetProduct(int id)
 {
    var product = _products.FirstOrDefault(p => p.ID == id);
    if (product == null)
    {
       throw new HttpResponseException(HttpStatusCode.NotFound);
    }
    return Request.CreateResponse(HttpStatusCode.OK, product);
 }

Cela fonctionne également pour les demandes entrantes à l’aide d’une fonctionnalité appelée Model Validation. Avec Model Validation, Web API2 est capable de valider et d’analyser les données de corps de réponse entrantes en un objet fortement typé avec lequel vous pouvez travailler dans votre code. Voici un exemple de liaison de modèle :

 public HttpResponseMessage Post(Product product)
 {
     if (ModelState.IsValid)
     {
         // Do something with the product (not shown).
 
         return new HttpResponseMessage(HttpStatusCode.OK);
     }
     else
     {
         return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
     }
 }

[1] : http://www.asp.net/vnext

Bonjour API Web

Web Api 2 - Exemple Hello World

Nous allons créer une nouvelle application simple Web Api qui nous renvoie Json avec message et nom d’utilisateur. Commençons! Créez d’abord un nouveau projet d’API Web à l’aide de Visual Studio et sélectionnez Modèle vide. Assurez-vous de vérifier le dossier “Web Api”:

[![entrez la description de l’image ici][1]][1]

REMARQUE Je n’ai pas choisi le modèle “Web Api” car il ajoute une référence à ASP.NET MVC pour fournir la page d’aide de l’API. Et dans une telle application de base, nous n’en avons pas vraiment besoin.

Ajout d’un modèle

Un modèle est une classe C# qui représente certaines données dans notre application. L’API Web ASP.NET est capable de sérialiser automatiquement le modèle en JSON, XML ou un autre format (selon la configuration).

Dans notre application, nous ne créerons qu’un seul modèle, mais les applications du monde réel en ont généralement beaucoup.

Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le dossier Modèles. Sélectionnez ensuite Ajouter, puis sélectionnez Classe. Nommez la classe “HelloMessage”. Notre modèle a besoin de deux propriétés : MessageText et UserName :

namespace WebApiHelloWorld.Models
{
    public class HelloMessage
    {
        public string MessageText { get; set; }
        public string UserName { get; set; }
    }
}

Ajout d’un contrôleur

Un contrôleur gère les requêtes HTTP. Notre application n’a besoin que d’un seul contrôleur qui renvoie Json avec le message Hello et le nom d’utilisateur (que nous transmettrons dans l’URL). Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le dossier Controllers. Sélectionnez ensuite Ajouter, puis sélectionnez Contrôleur. Dans la fenêtre ouverte, sélectionnez Web API Controller - Empty et cliquez sur Add.

[![entrez la description de l’image ici][2]][2]

Définissez le nom du contrôleur sur “HelloController”. Modifiez ensuite le code du contrôleur créé. Nous devons ajouter une méthode qui renvoie le message Hello.

using System.Web.Http;
using WebApiHelloWorld.Models;

namespace WebApiHelloWorld.Controllers
{
    public class HelloController : ApiController
    {
        public HelloMessage GetMessage(string name)
        {
            HelloMessage message = new HelloMessage
            {
                MessageText = "Hello my Dear!",
                UserName = name
            };

            return message;
        }
    }
}

REMARQUE Assurez-vous d’ajouter using WebApiHelloWorld.Models. Sans cela, votre contrôleur ne trouvera pas la classe HelloMessage.

Finir

C’est tout! Il ne vous reste plus qu’à créer et démarrer votre application. Appuyez simplement sur Ctrl + F5 ou simplement F5 (pour démarrer sans débogage). Visual studio lancera le navigateur Web. Vous devez appeler votre contrôleur. Pour cela ajouter à la fin de l’URL “/api/hello?name=John”. Le résultat devrait être :

{
    "MessageText": "Hello my Dear!",
    "UserName": "John"
}

[1] : https://i.stack.imgur.com/TPLtf.png [2] : https://i.stack.imgur.com/otR9M.png

Installation ou configuration

Instructions détaillées pour configurer ou installer asp.net-web-api 2.