Three Ways to Return Data from ASP.NET Core Web API

ASP.NET Core allows you to build RESTful services using web API. Typically you want to return data and HTTP status codes from an API controller. To that end there are three ways to return values from an API controller. This article discusses them with an example.

Return specific type

This is the most simplistic and straightforward way to return values from an API. Consider the following API action:

[HttpGet]
public List<Customer> Get()
{
    return db.Customers.ToList();
}

In this approach the Get() action returns a known type - List of Customer objects in this case. This approach is good if you simply want to return data to the client without accounting for unexpected conditions such as exceptions and HTTP codes such as 404 and 200.

Return IActionResult

When your return value is a mix of data and HTTP codes you can't use the previous approach. That's because the return type is a fix well-known type. If you want to return NotFoundResult or OkResult or ObjectResult you can't use the preceding approach. In such case you can return the values as IActionResult. Consider the following example:

[HttpGet("{id}")]
public IActionResult Get(string id)
{
    Customer cust = db.Customers.Find(id);
    if (cust == null)
    {
        return NotFound();
    }
    return Ok(cust);
}

In this case we want to return a particular customer based on the CustomerID passed in the action. It is possible that the CustomerID is invalid and Find() may fail to return a Customer object. If Find() return null we want to return 404 - Not Found response to the client. On the other hand if Customer is found we want to return 200 - Ok to the client along with the found Customer object.

This can be accomplished once we set the return type of IActionResult. The IActionResult interface is implemented by classes such as NotFoundResult and OkResult. The NotFound() and Ok() methods return these respective objects to the client.

Return ActionResult<T>

ActionResult<T> allows you to combine both of the approaches discussed earlier. You can return a type derived from ActionResult or a specific type. Consider the following Get() action:

[HttpGet("{id}")]
public ActionResult<Customer> Get(string id)
{
    Customer cust = db.Customers.Find(id);
    if (cust == null)
    {
        return NotFound();
    }
    return cust;
}

As you can see you don't need to wrap cust object in Ok() or ObjectResult. You can either return NotFoundResult or ActionResult<Customer>

That's it for now! Keep coding!!