Résultats des actions dans l’API Web 2

Article
07/16/2024

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

ASP.NET Core est une infrastructure open source multiplateforme 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’une des actions suivantes :

void
HttpResponseMessage
IHttpActionResult
Un autre type

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

Type renvoyé	Création de la réponse par l’API web
void	Retourner vide 204 (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 ; retour 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 le code d’état 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, à l’aide des propriétés de l’objet HttpResponseMessage pour remplir la réponse.

Cette option vous donne beaucoup de contrôle 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 Accept dans la requête 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 façon asynchrone une 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 httpResponseMessage en message de réponse HTTP.

Voici une implémentation simple d’IHttpActionResult qui crée une réponse de 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 du 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 des méthodes d’assistance qui retournent ces résultats d’action intégrés.

Dans l’exemple suivant, si la requête 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, 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. Le code d’état de la réponse 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 Accept dans la requête 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}]

Partager via

Résultats des actions dans l’API Web 2

void

HttpResponseMessage

IHttpActionResult

Autres types de retour

Commentaires

Ressources supplémentaires