Resultados de la acción en Web API 2

  • Artículo

Considere la posibilidad de usar la API Web de ASP.NET Core. Tiene las siguientes ventajas sobre API Web de ASP.NET 4.x:

  • ASP.NET Core es un marco multiplataforma de código abierto que tiene como finalidad compilar modernas aplicaciones web basadas en la nube en Windows, macOS y Linux.
  • Los controladores ASP.NET Core MVC y los controladores de API Web están unificados.
  • Diseñado para la capacidad de prueba.
  • Capacidad para desarrollarse y ejecutarse en Windows, macOS y Linux.
  • De código abierto y centrado en la comunidad.
  • Integración de marcos del lado cliente modernos y flujos de trabajo de desarrollo.
  • Un sistema de configuración basado en el entorno y preparado para la nube.
  • Inserción de dependencias integrada.
  • Una canalización de solicitudes HTTP ligera, modular y de alto rendimiento.
  • Capacidad de hospedar en Kestrel, IIS, HTTP.sys, Nginx, Apache y Docker.
  • Control de versiones en paralelo.
  • Herramientas que simplifican el desarrollo web moderno.

En este tema se describe cómo ASP.NET Web API convierte el valor devuelto de una acción del controlador en un mensaje de respuesta HTTP.

Una acción del controlador de Web API puede devolver cualquiera de las siguientes acciones:

  1. void
  2. HttpResponseMessage
  3. IHttpActionResult
  4. Otro tipo

Dependiendo de cuál de estos se devuelve, la Web API usa un mecanismo diferente para crear la respuesta HTTP.

Tipo de valor devuelto Cómo crea la Web API la respuesta
void Devolución de vacío 204 (sin contenido)
HttpResponseMessage Convierta directamente en un mensaje de respuesta HTTP.
IHttpActionResult Llame a ExecuteAsync para crear un HttpResponseMessagey, a continuación, convierta en un mensaje de respuesta HTTP.
Otro tipo Escriba el valor devuelto serializado en el cuerpo de la respuesta; return 200 (OK).

El resto de este tema describe cada opción con más detalle.

void

Si el tipo de valor devuelto es void, Web API simplemente devuelve una respuesta HTTP vacía con el código de estado 204 (sin contenido).

Controlador de ejemplo:

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

Respuesta HTTP:

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

HttpResponseMessage

Si la acción devuelve un HttpResponseMessage, Web API convierte el valor devuelto directamente en un mensaje de respuesta HTTP mediante las propiedades del objeto httpResponseMessage para rellenar la respuesta.

Esta opción proporciona un gran control sobre el mensaje de respuesta. Por ejemplo, la siguiente acción del controlador establece el encabezado 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;
    } 
}

Respuesta:

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 pasa un modelo de dominio al método CreateResponse, la Web API usa un formateador de medios para escribir el modelo serializado en el cuerpo de la respuesta.

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;
}

La Web API usa el encabezado Accept en la solicitud para elegir el formateador. Para obtener más información, consulte Negociación del contenido.

IHttpActionResult

La interfaz IHttpActionResult se introdujo en Web API 2. Básicamente, define una fábrica de HttpResponseMessage. Estas son algunas de las ventajas de usar la interfaz IHttpActionResult:

  • Simplifica las pruebas unitarias de los controladores.
  • Mueve la lógica común para crear respuestas HTTP en clases independientes.
  • Hace que la intención de la acción del controlador sea más clara, al ocultar los detalles de bajo nivel de la construcción de la respuesta.

IHttpActionResult contiene un único método, ExecuteAsync, que crea de forma asincrónica una instancia HttpResponseMessage.

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

Si una acción del controlador devuelve un IHttpActionResult, la Web API llama al método ExecuteAsync para crear un HttpResponseMessage. A continuación, convierte el HttpResponseMessage en un mensaje de respuesta HTTP.

Esta es una implementación sencilla de IHttpActionResult que crea una respuesta de texto sin formato:

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);
    }
}

Acción de controlador de ejemplo:

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

Respuesta:

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

Lo más habitual es utilizar las implementaciones de IHttpActionResult definidas en el espacio de nombres System.Web.Http.Results. La clase ApiController define los métodos auxiliares que devuelven estos resultados de acción integrados.

En el ejemplo siguiente, si la solicitud no coincide con un identificador de producto existente, el controlador llama a ApiController.NotFound para crear una respuesta 404 (no encontrado). De lo contrario, el controlador llama a ApiController.OK, que crea una respuesta 200 (OK) que contiene el producto.

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

Otros tipos de valor devuelto

Para todos los demás tipos de valor devuelto, la Web API usa un formateador de elementos multimedia para serializar el valor devuelto. La Web API escribe el valor serializado en el cuerpo de la respuesta. El código de estado de respuesta es 200 (Correcto).

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

Una desventaja de este enfoque es que no se puede devolver directamente un código de error, como 404. Sin embargo, puede iniciar una excepción HttpResponseException para los códigos de error. Para obtener más información, consulte Control de excepciones en ASP.NET Web API.

La Web API usa el encabezado Accept en la solicitud para elegir el formateador. Para obtener más información, consulte Negociación del contenido.

Solicitud de ejemplo

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

Respuesta de ejemplo

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}]