Partager via

Bien démarrer avec API Web ASP.NET 2 (C#)

  • Article

par Mike Wasson

Télécharger le projet terminé

Dans ce tutoriel, vous allez utiliser API Web ASP.NET pour créer une API web qui retourne une liste de produits.

HTTP n’est pas uniquement destiné à la mise en service de pages web. HTTP est également une plateforme puissante pour créer des API qui exposent des services et des données. HTTP est simple, flexible et omniprésent. Presque toutes les plateformes auxquelles vous pouvez penser disposent d’une bibliothèque HTTP, de sorte que les services HTTP peuvent atteindre un large éventail de clients, y compris les navigateurs, les appareils mobiles et les applications de bureau traditionnelles.

API Web ASP.NET est une infrastructure permettant de créer des API web au-dessus du .NET Framework.

Versions logicielles utilisées dans le tutoriel

Pour obtenir une version plus récente de ce didacticiel, consultez Créer une API web avec ASP.NET Core et Visual Studio pour Windows.

Créer un projet d’API web

Dans ce tutoriel, vous allez utiliser API Web ASP.NET pour créer une API web qui retourne une liste de produits. La page web frontale utilise jQuery pour afficher les résultats.

Capture d’écran de la fenêtre du navigateur de l’hôte local, montrant l’exemple de projet avec une liste de produits, leurs prix, ainsi qu’un champ et un bouton de recherche par ID.

Démarrez Visual Studio et sélectionnez Nouveau projet dans la page Démarrer . Ou, dans le menu Fichier , sélectionnez Nouveau , puis Projet.

Dans le volet Modèles , sélectionnez Modèles installés et développez le nœud Visual C# . Sous Visual C#, sélectionnez Web. Dans la liste des modèles de projet, sélectionnez ASP.NET application web. Nommez le projet « ProductsApp », puis cliquez sur OK.

Capture d’écran des options de modèle « Ajouter un nouveau projet », mettant en évidence les étapes et les sélections pour créer le nouveau projet.

Dans la boîte de dialogue Nouveau projet ASP.NET , sélectionnez le modèle Vide . Sous « Ajouter des dossiers et des références principales pour », case activée API web. Cliquez sur OK.

Capture d’écran de la boîte de dialogue nouveau projet, avec différentes options de modèle et trois sélections pour les dossiers et les références principales.

Notes

Vous pouvez également créer un projet d’API web à l’aide du modèle « API web ». Le modèle d’API web utilise ASP.NET MVC pour fournir des pages d’aide sur l’API. J’utilise le modèle Vide pour ce didacticiel, car je souhaite afficher l’API web sans MVC. En général, vous n’avez pas besoin de savoir ASP.NET MVC pour utiliser l’API Web.

Ajout d’un modèle

Un modèle est un objet qui représente les données dans votre application. API Web ASP.NET pouvez sérialiser automatiquement votre modèle au format JSON, XML ou autre, puis écrire les données sérialisées dans le corps du message de réponse HTTP. Tant qu’un client peut lire le format de sérialisation, il peut désérialiser l’objet. La plupart des clients peuvent analyser XML ou JSON. En outre, le client peut indiquer le format souhaité en définissant l’en-tête Accepter dans le message de requête HTTP.

Commençons par créer un modèle simple qui représente un produit.

Si l’Explorateur de solutions n’est pas déjà visible, cliquez sur le menu Vue et sélectionnez Explorateur de solutions. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le dossier Modèles. Dans le menu contextuel, sélectionnez Ajouter, puis Classe.

Capture d’écran du menu de l’Explorateur de solutions, affichant les options situées dans le dossier modèles montrant comment ajouter une classe.

Nommez la classe « Product ». Ajoutez les propriétés suivantes à la Product classe .

namespace ProductsApp.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }
}

Ajour d’un contrôleur

Dans l’API web, un contrôleur est un objet qui gère les requêtes HTTP. Nous allons ajouter un contrôleur qui peut retourner une liste de produits ou un seul produit spécifié par ID.

Notes

Si vous avez utilisé ASP.NET MVC, vous êtes déjà familiarisé avec les contrôleurs. Les contrôleurs d’API web sont similaires aux contrôleurs MVC, mais héritent de la classe ApiController au lieu de la classe Controller .

Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le dossier Contrôleurs. Sélectionnez Ajouter, puis Contrôleur.

Capture d’écran du menu de l’Explorateur de solutions affichant des conseils visuels pour l’ajout d’une classe de contrôleur au projet.

Dans la boîte de dialogue Ajouter une structure, cliquez sur Web API Controller - Empty (Contrôleur d’API web - Vide). Cliquez sur Add.

Capture d’écran montrant les options de menu de la boîte de dialogue « Ajouter une structure », mettant en évidence l’option vide du contrôleur Web A P I.

Dans la boîte de dialogue Ajouter un contrôleur , nommez le contrôleur « ProductsController ». Cliquez sur Add.

Capture d’écran de la boîte de dialogue « ajouter un contrôleur », en mettant le mot « contrôleur de produits » dans la zone de champ et le bouton Ajouter sous celle-ci.

La structure crée un fichier nommé ProductsController.cs dans le dossier Controllers.

Capture d’écran des options de menu de l’Explorateur de solutions, encerclant l’option nouvellement créée appelée « products controller dot C S » dans le dossier contrôleurs.

Notes

Vous n’avez pas besoin de placer vos contrôleurs dans un dossier nommé Contrôleurs. Le nom du dossier est simplement un moyen pratique d’organiser vos fichiers sources.

Si ce fichier n’est pas déjà ouvert, double-cliquez dessus pour l’ouvrir. Remplacez le code dans ce fichier par les éléments suivants :

using ProductsApp.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Web.Http;

namespace ProductsApp.Controllers
{
    public class ProductsController : ApiController
    {
        Product[] products = new Product[] 
        { 
            new Product { Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1 }, 
            new Product { Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M }, 
            new Product { Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M } 
        };

        public IEnumerable<Product> GetAllProducts()
        {
            return products;
        }

        public IHttpActionResult GetProduct(int id)
        {
            var product = products.FirstOrDefault((p) => p.Id == id);
            if (product == null)
            {
                return NotFound();
            }
            return Ok(product);
        }
    }
}

Pour que l’exemple reste simple, les produits sont stockés dans un tableau fixe à l’intérieur de la classe contrôleur. Bien sûr, dans une application réelle, vous interrogez une base de données ou utilisez une autre source de données externe.

Le contrôleur définit deux méthodes qui retournent des produits :

  • La GetAllProducts méthode retourne la liste complète des produits sous la forme d’un type de produit> IEnumerable<.
  • La GetProduct méthode recherche un seul produit par son ID.

Et voilà ! Vous disposez d’une API web de travail. Chaque méthode sur le contrôleur correspond à un ou plusieurs URI :

Controller, méthode URI
GetAllProducts /api/products
GetProduct /api/products/id

Pour la GetProduct méthode, l’ID dans l’URI est un espace réservé. Par exemple, pour obtenir le produit avec l’ID 5, l’URI est api/products/5.

Pour plus d’informations sur la façon dont l’API web achemine les requêtes HTTP vers les méthodes de contrôleur, consultez Routage dans API Web ASP.NET.

Appel de l’API web avec Javascript et jQuery

Dans cette section, nous allons ajouter une page HTML qui utilise AJAX pour appeler l’API web. Nous allons utiliser jQuery pour effectuer les appels AJAX et mettre à jour la page avec les résultats.

Dans Explorateur de solutions, cliquez avec le bouton droit sur le projet, sélectionnez Ajouter, puis sélectionnez Nouvel élément.

Capture d’écran du menu de l’Explorateur de solutions, mettant en évidence l’option d’application products pour afficher ses sélections de menu pour ajouter un nouvel élément.

Dans la boîte de dialogue Ajouter un nouvel élément , sélectionnez le nœud Web sous Visual C#, puis sélectionnez l’élément Page HTML . Nommez la page « index.html ».

Capture d’écran des options de menu « Ajouter un nouvel élément », montrant la sélection web et les options disponibles dans celle-ci.

Remplacez tout ce qui se trouve dans ce fichier par les éléments suivants :

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Product App</title>
</head>
<body>

  <div>
    <h2>All Products</h2>
    <ul id="products" />
  </div>
  <div>
    <h2>Search by ID</h2>
    <input type="text" id="prodId" size="5" />
    <input type="button" value="Search" onclick="find();" />
    <p id="product" />
  </div>

  <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js"></script>
  <script>
    var uri = 'api/products';

    $(document).ready(function () {
      // Send an AJAX request
      $.getJSON(uri)
          .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
              // Add a list item for the product.
              $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
          });
    });

    function formatItem(item) {
      return item.Name + ': $' + item.Price;
    }

    function find() {
      var id = $('#prodId').val();
      $.getJSON(uri + '/' + id)
          .done(function (data) {
            $('#product').text(formatItem(data));
          })
          .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
          });
    }
  </script>
</body>
</html>

Il existe plusieurs façons d’obtenir jQuery. Dans cet exemple, j’ai utilisé le CDN Microsoft Ajax. Vous pouvez également le télécharger à partir de http://jquery.com/, et le modèle de projet « API web » ASP.NET inclut également jQuery.

Obtention d’une liste de produits

Pour obtenir la liste des produits, envoyez une requête HTTP GET à « /api/products ».

La fonction jQuery getJSON envoie une requête AJAX. La réponse contient un tableau d’objets JSON. La done fonction spécifie un rappel appelé si la requête réussit. Dans le rappel, nous mettons à jour le DOM avec les informations sur le produit.

$(document).ready(function () {
    // Send an AJAX request
    $.getJSON(apiUrl)
        .done(function (data) {
            // On success, 'data' contains a list of products.
            $.each(data, function (key, item) {
                // Add a list item for the product.
                $('<li>', { text: formatItem(item) }).appendTo($('#products'));
            });
        });
});

Obtention d’un produit par ID

Pour obtenir un produit par ID, envoyez une requête HTTP GET à « /api/products/id », où id est l’ID de produit.

function find() {
    var id = $('#prodId').val();
    $.getJSON(apiUrl + '/' + id)
        .done(function (data) {
            $('#product').text(formatItem(data));
        })
        .fail(function (jqXHR, textStatus, err) {
            $('#product').text('Error: ' + err);
        });
}

Nous appelons getJSON toujours pour envoyer la requête AJAX, mais cette fois, nous avons placé l’ID dans l’URI de la demande. La réponse de cette demande est une représentation JSON d’un seul produit.

Exécution de l'application

Appuyez sur F5 pour lancer le débogage de l’application. La page web doit se présenter comme suit :

Capture d’écran du navigateur web, montrant une puce tous les produits, avec leurs prix, suivie du champ « search by ID » sous celui-ci.

Pour obtenir un produit par ID, entrez l’ID et cliquez sur Rechercher :

Capture d’écran du navigateur, montrant tous les produits et prix, sous forme de puces, et le numéro 2 dans le champ « rechercher par ID ».

Si vous entrez un ID non valide, le serveur retourne une erreur HTTP :

Capture d’écran du navigateur, répertoriant tous les produits et leurs prix, et montrant le message d’erreur « introuvable » sous le champ « rechercher par ID ».

Utilisation de F12 pour afficher la requête et la réponse HTTP

Lorsque vous utilisez un service HTTP, il peut être très utile d’afficher les messages de requête et de réponse HTTP. Pour ce faire, utilisez les outils de développement F12 dans Internet Explorer 9. À partir d’Internet Explorer 9, appuyez sur F12 pour ouvrir les outils. Cliquez sur l’onglet Réseau , puis appuyez sur Démarrer la capture. Revenez maintenant à la page web et appuyez sur F5 pour recharger la page web. Les Explorer Internet capturent le trafic HTTP entre le navigateur et le serveur web. La vue récapitulative affiche tout le trafic réseau pour une page :

Capture d’écran de la fenêtre de message de demande et de réponse DE TGH, montrant une liste d’URL et toutes les réponses au trafic réseau.

Recherchez l’entrée pour l’URI relatif « api/products/ ». Sélectionnez cette entrée, puis cliquez sur Accéder à l’affichage détaillé. Dans l’affichage détaillé, il existe des onglets pour afficher les en-têtes et les corps de la demande et de la réponse. Par exemple, si vous cliquez sur l’onglet En-têtes de requête, vous pouvez voir que le client a demandé « application/json » dans l’en-tête Accepter.

Capture d’écran de la boîte de dialogue de message de demande et de réponse DE TGH, montrant un exemple de réponse à une demande d’API individuelle.

Si vous cliquez sur l’onglet Corps de la réponse, vous pouvez voir comment la liste de produits a été sérialisée au format JSON. D’autres navigateurs ont des fonctionnalités similaires. Un autre outil utile est Fiddler, un proxy de débogage web. Vous pouvez utiliser Fiddler pour afficher votre trafic HTTP, ainsi que pour composer des requêtes HTTP, ce qui vous donne un contrôle total sur les en-têtes HTTP dans la requête.

Voir cette application en cours d’exécution sur Azure

Voulez-vous voir le site terminé s’exécuter en tant qu’application web active ? Vous pouvez déployer une version complète de l’application sur votre compte Azure.

Vous avez besoin d’un compte Azure pour déployer cette solution sur Azure. Si vous n’avez pas encore de compte, vous disposez des options suivantes :

  • Ouvrez un compte Azure gratuitement : vous obtenez des crédits que vous pouvez utiliser pour tester les services Azure payants, et même après leur utilisation, vous pouvez conserver le compte et utiliser des services Azure gratuits.
  • Activer les avantages de l’abonné MSDN : votre abonnement MSDN vous donne des crédits chaque mois que vous pouvez utiliser pour les services Azure payants.

Étapes suivantes