Résultats des actions dans l’API Web 2

  • Article

Envisagez d’utiliser ASP.NET Core API web. Il présente les avantages suivants par rapport à ASP.NET API Web 4.x :

  • ASP.NET Core est une infrastructure multiplateforme open source permettant de créer des applications web modernes basées sur le cloud sur Windows, macOS et Linux.
  • Les contrôleurs MVC ASP.NET Core et les contrôleurs d’API web sont unifiés.
  • Architecturé pour la testabilité.
  • Capacité à développer et à exécuter sur Windows, macOS et Linux.
  • Open source et centré sur la communauté.
  • Intégration de frameworks modernes côté client et de workflows de développement.
  • Un système de configuration prêt pour le cloud et basé sur les environnements.
  • Injection de dépendances intégrée.
  • Un pipeline des requêtes HTTP léger, à hautes performances et modulaire.
  • Possibilité d’héberger sur Kestrel, IIS, HTTP.sys, Nginx, Apache et Docker.
  • Contrôle de version côte à côte.
  • Outils qui simplifient le développement web moderne.

Cette rubrique décrit comment API Web ASP.NET convertit la valeur de retour d’une action de contrôleur en message de réponse HTTP.

Une action de contrôleur d’API web peut retourner l’un des éléments suivants :

  1. void
  2. HttpResponseMessage
  3. IHttpActionResult
  4. Un autre type

En fonction de l’objet retourné, l’API web utilise un mécanisme différent pour créer la réponse HTTP.

Type de retour Comment l’API web crée la réponse
void Retourner la valeur 204 vide (aucun contenu)
HttpResponseMessage Convertissez directement en message de réponse HTTP.
IHttpActionResult Appelez ExecuteAsync pour créer un HttpResponseMessage, puis convertissez en message de réponse HTTP.
Autre type Écrivez la valeur de retour sérialisée dans le corps de la réponse ; retourne 200 (OK).

Le reste de cette rubrique décrit chaque option plus en détail.

void

Si le type de retour est void, l’API web retourne simplement une réponse HTTP vide avec status code 204 (Aucun contenu).

Exemple de contrôleur :

public class ValuesController : ApiController
{
    public void Post()
    {
    }
}

Réponse HTTP :

HTTP/1.1 204 No Content
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 02:13:26 GMT

HttpResponseMessage

Si l’action retourne un HttpResponseMessage, l’API web convertit la valeur de retour directement en message de réponse HTTP, en utilisant les propriétés de l’objet HttpResponseMessage pour remplir la réponse.

Cette option vous donne un contrôle important sur le message de réponse. Par exemple, l’action de contrôleur suivante définit l’en-tête Cache-Control.

public class ValuesController : ApiController
{
    public HttpResponseMessage Get()
    {
        HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, "value");
        response.Content = new StringContent("hello", Encoding.Unicode);
        response.Headers.CacheControl = new CacheControlHeaderValue()
        {
            MaxAge = TimeSpan.FromMinutes(20)
        };
        return response;
    } 
}

Réponse :

HTTP/1.1 200 OK
Cache-Control: max-age=1200
Content-Length: 10
Content-Type: text/plain; charset=utf-16
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT

hello

Si vous passez un modèle de domaine à la méthode CreateResponse , l’API web utilise un formateur multimédia pour écrire le modèle sérialisé dans le corps de la réponse.

public HttpResponseMessage Get()
{
    // Get a list of products from a database.
    IEnumerable<Product> products = GetProductsFromDB();

    // Write the list to the response body.
    HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, products);
    return response;
}

L’API web utilise l’en-tête Accepter dans la demande pour choisir le formateur. Pour plus d’informations, consultez Négociation de contenu.

IHttpActionResult

L’interface IHttpActionResult a été introduite dans l’API Web 2. Essentiellement, il définit une fabrique HttpResponseMessage . Voici quelques avantages de l’utilisation de l’interface IHttpActionResult :

  • Simplifie le test unitaire de vos contrôleurs.
  • Déplace la logique courante pour la création de réponses HTTP dans des classes distinctes.
  • Rend l’intention de l’action du contrôleur plus claire, en masquant les détails de bas niveau de construction de la réponse.

IHttpActionResult contient une méthode unique, ExecuteAsync, qui crée de manière asynchrone un instance HttpResponseMessage.

public interface IHttpActionResult
{
    Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken);
}

Si une action de contrôleur retourne un IHttpActionResult, l’API web appelle la méthode ExecuteAsync pour créer un HttpResponseMessage. Ensuite, il convertit le HttpResponseMessage en message de réponse HTTP.

Voici une implémentation simple d’IHttpActionResult qui crée une réponse en texte brut :

public class TextResult : IHttpActionResult
{
    string _value;
    HttpRequestMessage _request;

    public TextResult(string value, HttpRequestMessage request)
    {
        _value = value;
        _request = request;
    }
    public Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
    {
        var response = new HttpResponseMessage()
        {
            Content = new StringContent(_value),
            RequestMessage = _request
        };
        return Task.FromResult(response);
    }
}

Exemple d’action de contrôleur :

public class ValuesController : ApiController
{
    public IHttpActionResult Get()
    {
        return new TextResult("hello", Request);
    }
}

Réponse :

HTTP/1.1 200 OK
Content-Length: 5
Content-Type: text/plain; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT

hello

Plus souvent, vous utilisez les implémentations IHttpActionResult définies dans l’espace de noms System.Web.Http.Results . La classe ApiController définit les méthodes d’assistance qui retournent ces résultats d’action intégrés.

Dans l’exemple suivant, si la demande ne correspond pas à un ID de produit existant, le contrôleur appelle ApiController.NotFound pour créer une réponse 404 (introuvable). Sinon, le contrôleur appelle ApiController.OK, ce qui crée une réponse 200 (OK) qui contient le produit.

public IHttpActionResult Get (int id)
{
    Product product = _repository.Get (id);
    if (product == null)
    {
        return NotFound(); // Returns a NotFoundResult
    }
    return Ok(product);  // Returns an OkNegotiatedContentResult
}

Autres types de retour

Pour tous les autres types de retour, l’API web utilise un formateur multimédia pour sérialiser la valeur de retour. L’API web écrit la valeur sérialisée dans le corps de la réponse. La réponse status code est 200 (OK).

public class ProductsController : ApiController
{
    public IEnumerable<Product> Get()
    {
        return GetAllProductsFromDB();
    }
}

L’inconvénient de cette approche est que vous ne pouvez pas retourner directement un code d’erreur, tel que 404. Toutefois, vous pouvez lever une exception HttpResponseException pour les codes d’erreur. Pour plus d’informations, consultez Gestion des exceptions dans API Web ASP.NET.

L’API web utilise l’en-tête Accepter dans la demande pour choisir le formateur. Pour plus d’informations, consultez Négociation de contenu.

Exemple de requête

GET http://localhost/api/products HTTP/1.1
User-Agent: Fiddler
Host: localhost:24127
Accept: application/json

Exemple de réponse

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT
Content-Length: 56

[{"Id":1,"Name":"Yo-yo","Category":"Toys","Price":6.95}]