Every .NET Core Web API controller has some Actions defined. Each Action is a public method which has some input parameters and each action has some return type.

In previous post, we have seen how the data from incoming HTTP request can be bound to the input parameters.

.NET Core API actions support various return types. In this article, we will have a look at what are the options and what are pros and cons of every choice.

Return Specific Type

Actions are public methods inside API controllers. Hence, simplest choice is to use a specific type as return type for the action, like any other method.

e.g. if you create an action, GetCustomer, then it can return an object of class Customer.

If the action is supposed to return collection, IEnumerable or List or any other collection type can be used as return type.

Below code example shows that return type for the post action is SubjectSummary, a class defined in API project.

Return IActionResult

IActionResult is the interface which represents result of an action. An abstract class ActionResult is derived from this interface and from this abstract class, there are various types of ActionResult implementation.

Below is the list of most common implementations of IActionResult:

• Microsoft.AspNetCore.Mvc.EmptyResult
• Microsoft.AspNetCore.Mvc.ContentResult
• Microsoft.AspNetCore.Mvc.FileResult
• Microsoft.AspNetCore.Mvc.JsonResult
• Microsoft.AspNetCore.Mvc.ChallengeResult
• Microsoft.AspNetCore.Mvc.SignInResult
• Microsoft.AspNetCore.Mvc.SignOutResult

There are also some action results implementations which can be used to return status codes:

• Microsoft.AspNetCore.Mvc.BadRequestResult
• Microsoft.AspNetCore.Mvc.NotFoundResult
• System.Web.Http.InternalServerErrorResult

For full list of IActionResult implementations, refer the documentation.

Returning IActionResult is helpful in scenarios where the web API action is supposed to return multiple types. e.g. if record not found, then action can return NotFoundResult and if Record is found then API can return 200 OK with record to the caller.

Below code example shows how IActionResult can be used.

Return ActionResult<T>

This is combination of the two options mentioned above.

ActionResult<T> was introduced so that the Web API action should be able to return either some IActionResult or specific type (specified via type parameter T).

In this approach, implicit casting is supported to convert either T or even ActionResult to ActionResult<T>. What does it mean ?

It means that you can make the code more readable by just returning specific type using statement return T; OR if you want to return some http status code result, that can also be done by just returning let’s say NotFoundResult or BadRequestResult – without specifying the type.

Implicit conversions are tricky sometimes. C# does not support implicit conversions on interfaces.

Especially, when the action is supposed to return collection and you specify interface type parameter (e.g. ActionResult<IEnumerable> ), you might want to return a concrete type (e.g. List) instead of returning IList or IEnumerable interface.

Which one is the best choice ?

I personally believe returning specific type from the Web API action is NOT that helpful from error handling perspective – especially when controller action is going to validate some things and want to return HTTP Status code result. Having specific return type would force you to return either the specific type or throw an exception.

Between IActionResult and ActionResult<T>, in my opinion. They allow to return different concrete ActionResult implementation, based on need of the action.

I would still prefer ActionResult<T> as the return type in my Web API project. It makes the signature convey everything about the action – so it improves readability. Also, as it allows to return specific types it also implies maintainability and better type safety than returning IActionResult.

Do you share different opinion about this ? I would love to hear back from you.