What should be the return type of WEB API Action Method?

Question

I am developing ASP.NET Web API using .NET Core. This Web API is going to be mainly accessed by UI application (UI will be developed using ASP.NET Core MVC) but in future API may be accessed by other applications as well.

In my WEB API all methods are async.

If I want client to do content negotiation then what should be the return type of the API action method Task<IActionresult> or Task<SomePOCO>

If I want method to always return data in JSON format then what should be return type of the API action method? Should it be Task<IActionResult> or Task<JsonResult> or Task<SomePOCO> because I think all 3 would work so not sure which one is appropriate here?

Answer 1

If I want [the] client to do content negotiation then what should be the return type of the API action method?

To do content negotiation, return Task<ObjectResult> or Task<MyPoco>.

The framework automatically wraps POCOs in an ObjectResult; therefor, both options are equivalent, and both will obey the HTTP Accept header. You will also get content negotiation by returning any result that implements ObjectResult, such as an OkObjectResult does.

If I want [the] method to always return data in JSON format then what should be [the] return type of the API action method?

To always return JSON, return a Task<JsonResult> (or use the [Produces] filter).

See also: https://docs.asp.net/en/latest/mvc/models/formatting.html#content-negotiation

[S]o I am assuming then IActionResult is only used for MVC controller?

IActionResult is the contract for all results that a Controller returns. If your action's signature has an IActionResult return type, then your action's method body can return any result type, because all of them implement the IActionResult interface. Here is the inheritance hierarchy.

IActionResult
  ActionResult
    ChallengeResult 
    ContentResult 
    EmptyResult 
    FileResult 
      FileContentResult 
      FileStreamResult 
      PhysicalFileResult 
      VirtualFileResult 
    ForbidResult 
    LocalRedirectResult 
    ObjectResult
      CreatedAtActionResult 
      CreatedAtRouteResult 
      CreatedResult 
      BadRequestObjectResult 
      NotFoundObjectResult 
      OkObjectResult 
    RedirectResult 
    RedirectToActionResult 
    RedirectToRouteResult 
    SignInResult 
    SignOutResult 
    StatusCodeResult 
      NoContentResult 
      NotFoundResult 
      OkResult 
      UnauthorizedResult 
      UnsupportedMediaTypeResult 
      BadRequestResult 

See also: https://github.com/aspnet/Mvc/tree/dev/src/Microsoft.AspNetCore.Mvc.Core

Answer 2

Have a look at swagger: https://learn.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger It's better to specify ProducesResponseType attribute for method:

[ProducesResponseType(typeof(TodoItem), 201)]
public IActionResult Create([FromBody, Required] TodoItem item)

So that automatically generated swagger documentation to show the actual returned data for the method.