ASP.NET Web API 2 action method return types

Here, in this article we will learn ASP.NET Web API 2 action method return types.

A Web API 2 action method return types can be any of the following :

• Void
• HttpResponseMessage
• IHttpActionResult
• Other type or Complex type

Void

When an ASP.NET Web API return type is void, it will return an empty HTTP response.

In the following example a web API with void return:

Example

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

Note: We are using fiddler to call Web API, it is a free web debugging proxy which logs all HTTP(s) traffic between your computer and the Internet

Result

Calling sample web API in fiddler

 

It is returning status code 204 No Content (an empty HTTP response)

 

HttpResponseMessage

• When Web API return type is HttpResponseMessage, Web API converts the return value directly into an HTTP response message.
• We can set the status code, content as per our requirement.

In the following example a web API with HttpResponseMessage return:

Example

public HttpResponseMessage Get()
{
    HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, "value1");            
    return response;
}

Result

Calling sample Web API with HTTP GET request

 

In Response, It is returning status code 200 OK and Content

 

Note:Web API serialized model into the response body based on request header formatter

In the following example a web API return HttpResponseMessage with list of Countries in response body:

Example

public HttpResponseMessage Get()
{
   // list of Countries
   List Countries = new List();
    Country country = new Country();
    country.ID = 1;
    country.CountryName = "USA";
    country.Capital = "Washington";
    Countries.Add(country);
        
    //Countries to the response body.             
    HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, Countries);            
    return response;
}

Result

In Response, It is returning status code 200 OK and Content

 

IHttpActionResult

IHttpActionResult is introduced in Web API 2, IHttpActionResult interface acts like a factory for HttpResponseMessage.

There are some advantages of using the IHttpActionResult over HttpResponseMessage

• The code is cleaner and easier to read
• Unit testing for controller action methods become easy
• It comes with custom built in responses
  • Ok
  • NotFound
  • Exception
  • Unauthorized
  • BadRequest
  • Conflict
  • Redirect

In the following example a web API return IHttpActionResult with list of Countries in response body:

Example

public IHttpActionResult Get(int id)
{
   // list of Countries
   List Countries = new List();
    Country country = new Country();
    country.ID = 1;
    country.CountryName = "USA";
    country.Capital = "Washington";
    Countries.Add(country);
    
    //finding country based on provided id
    var result = Countries.FirstOrDefault(x=> x.ID ==id);
    if (result == null)
    {
        //create a 404 (Not Found) response
        return NotFound();                
    }
    else
    {
        //creates a 200 (OK) response that contains the country
        return Ok(result);
    }
}

Result

Calling sample web API with HTTP GET request and id

 

In Response, It is returning status code 200 OK and Content

 

Calling sample web API with HTTP GET request and id(which is not exist)

 

In Response, It is returning status code 404 Not Found

 

Other type or Complex type

• A Web API can return other or custom complex type
• Web API serialize value and return it into the response body
• The response status code 200 OK
• But in this approach we cannot directly return an error code, still we can throw an HttpResponseException for error codes

In the following example a web API with Complex return type:

Example

public class CountryController : ApiController
{
    public IEnumerable Get()
    {
        List Countries = new List();
        Country country = new Country();
        country.ID = 1;
        country.CountryName = "USA";
        country.Capital = "Washington";
        Countries.Add(country);
        return Countries;
    }
}

Result

Calling Country web API with HTTP GET request

 

In Response, It is returning status code 200 OK and Content