이번 주제는 ASP.NET Web API에서 응답 메시지를 반환하는 경우, 반환 값을 컨트롤러 액션에서 HTTP 응답 메시지로 어떻게 변환할 수 있는 지를 설명한다.

Web API 컨트롤러 액션은 다음 중 하나의 유형을 반환할 수 있다

1. void
2. HttpResponseMessage
3. IHttpActionResult
4. 그 밖의 형식

이 중 어떤 것이 반환되느냐에 따라 Web API는 각기 다른 메카니즘을 사용하여 HTTP 응답을 생성한다.

이번 글에서는 이러한 각각의 옵션에 대해서는 자세히 다룰 예정이다

void

만일 반환 형식이 void라면, Web API는 단순히 비어있는 HTTP 응답을 상태코드 204(No Content)와 함께 반환한다.

컨트롤러 예제 :

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

HTTP 응답 :

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

HttpResponseMessage

만일 액션이 HttpResponseMessage를 반환한다면, Web API는 반환 값을 HTTP 응답 메세지로 곧바로 변환하게 되는데, 응답 메세지는 HttpResponseMessage 개체의 속성들을 사용하여 구성한다.

이 옵션을 사용하면 응답 메세지에 다양한 설정을 추가할 수가 있는데, 예를 들면 다음 컨트롤러 액션은 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;
    } 
}

응답 :

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

만약 도메인 모델을 CreateResponse 메서드로 전달한다면 Web API는 media formatter를 사용해서 직렬화된 모델을 응답 본문에 작성하게 된다.

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

Web API는 요청에 포함되어 있는 Accept 헤더를 사용하여 적절한 포매터를 선택한다. 이에 대한 좀 더 자세한 내용은 Content Negotiation를 참고하자.

IHttpActionResult

IHttpActionResult 인터페이스는 Web API 2에서 처음 소개된 녀석으로서 기본적으로 HttpResponseMessage 팩토리를 정의하고 있다. 다음은 IHttpActionResult 인터페이스를 사용할 경우 얻을 수 있는 몇몇 장점이다 :

• 여러분의 컨트롤러에 대한 단위 테스트를 용이하게 한다
• HTTP 응답을 생성하는 공통 로직들을 별개의 클래스로 옮길 수 있다.
• 컨트롤러 액션의 의도를 명확하게 만들 수 있다(응답을 구성하는 저수준의 복잡한 내용들을 드러나지 않도록 하여)

IHttpActionResult는 단일 메서드로서 ExecuteAsync를 갖고 있는데, 이는 비동기적으로 HttpResponseMessage 인스턴스를 생성한다.

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

만일 컨트롤러 액션이 IHttpActionResult를 반환한다면, Web API는 ExecuteAsync 메서드를 호출하여 HttpResponseMessage를 생성한 다음 그를 HTTP 응답 메세지로 변환한다

다음은 일반적인 텍스트 응답을 생성하는 간단한 IHttpActionResult의 구현 예이다 :

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

예제 컨트롤러 액션 :

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

응답 :

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

예상보다 자주 여러분은 System.Web.Http.Results 네임스페이스에 정의되어 있는 IHttpActionResult 구현을 사용하게 될 것이다. 그렇기에, ApiContoller 클래스는 이러한 내장된 액션 결과들을 반환하는 도우미 메서드들도 제공해주고 있다.

다음 예제에서는 요청된 제품의 ID가 존재하지 않을 경우 404(Not Found) 응답을 제공하기 위해서 컨트롤러가 ApiController.NotFound를 호출하는 예를 보여주고 있다. 그리고, 만일 제품이 존재한다면 제품 정보를 포함하여 200 (OK) 응답을 생성하는 ApiController.OK를 호출하고 있다.

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

그 밖의 반환 형식

그 밖의 모든 반환 형식들에 대해서는 Web API가 미디어 포매터(media formatter)를 사용하여 반환 값을 직렬화한다. Web API는 직렬화된 값을 응답 본문에 작성하며, 이 경우 응답 상태 코드는 200(OK)이다.

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

이 방식의 문제점은 에러 코드(예를 들면, 404)를 직접 반환할 수가 없다는 점이다. 하지만, HttpResponseException를 던지는 방식으로 이 문제를 우회할 수 있긴 할 것이다. 더 자세한 내용은 Exception Handling in ASP.NET Web API를 참고하도록 하자.

더불어, Web API는 요청 안에 포함되어 있는 Accept 헤더를 확인하여 적절한 포매터를 결정한다.이에 대한 자세한 내용은 Content Negotiation를 참고하도록 하자.

요청 예

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

응답 예 :

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