Resultados da ação na API Web 2

Artigo
07/16/2024

Considere usar ASP.NET API Web principal. Ele tem as seguintes vantagens sobre ASP.NET API Web 4.x:

ASP.NET Core é uma estrutura de plataforma cruzada de código aberto para criar aplicativos Web modernos baseados em nuvem no Windows, macOS e Linux.
Os controladores MVC do ASP.NET Core e os controladores de API Web são unificados.
Projetado para capacidade de teste.
Capacidade de desenvolver e executar no Windows, macOS e Linux.
De software livre e voltado para a comunidade.
Integração de estruturas modernas do lado do cliente e fluxos de trabalho de desenvolvimento.
Um sistema de configuração pronto para a nuvem, baseado no ambiente.
Injeção de dependência interna.
Um pipeline de solicitação HTTP leve, modular e de alto desempenho.
Capacidade de hospedar no Kestrel, IIS, HTTP.sys, Nginx, Apache e Docker.
Controle de versão lado a lado.
Ferramentas que simplificam o moderno desenvolvimento para a Web.

Este tópico descreve como ASP.NET API Web converte o valor retornado de uma ação do controlador em uma mensagem de resposta HTTP.

Uma ação do controlador da API Web pode retornar qualquer um dos seguintes:

void
Mensagem de resposta HTTP
IHttpActionResult
Algum outro tipo

Dependendo de qual deles é retornado, a API Web usa um mecanismo diferente para criar a resposta HTTP.

Tipo de retorno	Como a API Web cria a resposta
void	Retornar vazio 204 (Sem Conteúdo)
Mensagem de resposta HTTP	Converta diretamente em uma mensagem de resposta HTTP.
IHttpActionResult	Chame ExecuteAsync para criar um HttpResponseMessage e, em seguida, converta em uma mensagem de resposta HTTP.
Outro tipo	Escreva o valor retornado serializado no corpo da resposta; retornar 200 (OK).

O restante deste tópico descreve cada opção com mais detalhes.

void

Se o tipo de retorno for void, a API Web simplesmente retornará uma resposta HTTP vazia com o código de status 204 (Sem Conteúdo).

Exemplo de controlador:

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

Resposta HTTP:

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

HttpResponseMessage

Se a ação retornar um HttpResponseMessage, a API Web converterá o valor retornado diretamente em uma mensagem de resposta HTTP, usando as propriedades do objeto HttpResponseMessage para preencher a resposta.

Essa opção oferece muito controle sobre a mensagem de resposta. Por exemplo, a ação do controlador a seguir define o cabeçalho 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;
    } 
}

Resposta:

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

Se você passar um modelo de domínio para o método CreateResponse, a API Web usará um formatador de mídia para gravar o modelo serializado no corpo da resposta.

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

A API Web usa o cabeçalho Accept na solicitação para escolher o formatador. Para obter mais informações, consulte Negociação de conteúdo.

IHttpActionResult

A interface IHttpActionResult foi introduzida na API Web 2. Essencialmente, ele define uma fábrica HttpResponseMessage . Aqui estão algumas vantagens de usar a interface IHttpActionResult :

Simplifica o teste de unidade de seus controladores.
Move a lógica comum para criar respostas HTTP em classes separadas.
Torna a intenção da ação do controlador mais clara, ocultando os detalhes de baixo nível da construção da resposta.

IHttpActionResult contém um único método, ExecuteAsync, que cria de forma assíncrona uma instância HttpResponseMessage .

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

Se uma ação do controlador retornar um IHttpActionResult, a API Web chamará o método ExecuteAsync para criar um HttpResponseMessage. Em seguida, ele converte o HttpResponseMessage em uma mensagem de resposta HTTP.

Aqui está uma implementação simples de IHttpActionResult que cria uma resposta de texto sem formatação:

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

Exemplo de ação do controlador:

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

Resposta:

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

Mais frequentemente, você usa as implementações IHttpActionResult definidas no namespace System.Web.Http.Results . A classe ApiController define métodos auxiliares que retornam esses resultados de ação internos.

No exemplo a seguir, se a solicitação não corresponder a uma ID de produto existente, o controlador chamará ApiController.NotFound para criar uma resposta 404 (Not Found). Caso contrário, o controlador chamará ApiController.OK, que cria uma resposta 200 (OK) que contém o produto.

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

Outros tipos de devolução

Para todos os outros tipos de retorno, a API Web usa um formatador de mídia para serializar o valor retornado. A API Web grava o valor serializado no corpo da resposta. O código de status da resposta é 200 (OK).

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

Uma desvantagem dessa abordagem é que você não pode retornar diretamente um código de erro, como 404. No entanto, você pode lançar um HttpResponseException para códigos de erro. Para obter mais informações, consulte Tratamento de exceções na API Web ASP.NET.

A API Web usa o cabeçalho Accept na solicitação para escolher o formatador. Para obter mais informações, consulte Negociação de conteúdo.

Solicitação de exemplo

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

Exemplo de resposta

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

Compartilhar via

Resultados da ação na API Web 2

void

HttpResponseMessage

IHttpActionResult

Outros tipos de devolução

Comentários

Recursos adicionais