What is the difference in returning “JsonResult/IActionResult” or “Task<SomeObject>” or just “SomeObject” in a Asp.net Core Web API?

Question

Consider the following method signatures for an ASP.NET Core web API controller method:

public JsonResult GetById(string id);
public async Task<SomeObject> GetById(string id);
public SomeObject GetById(string id)

In the default setup, all return a JSON representation of SomeObject to the client. Does the framework treat them differently, and if so which should be used when?

For example, most documentation recommends the use of an implementation of IActionResult generated by helper functions such as OK() . However, all these seem to do for you is set the StatusCode, and they have the downside of obfuscating what your method returns - in fact you could return different types in different situations, which I think is a terrible idea. A knock-on effect is that tools like Swagger cannot predict what the method will return.

So I'd prefer to return SomeObject :

1. am I missing something important?, and
2. What are the benefits of returning Task<SomeObject> - is it always useful, or only if the method uses asynchronous calls?

Edit: Attempt to clarify - all signatures return a JSON representation of SomeObject to the client, but from a C# point of view they have different return types, so the MVC framework is doing some work to convert them.

Which is best practice and why? Is there a good reason to return JsonResult rather than returning SomeObject ? Should returning Task<SomeObject> always be used, or is it only valuable (I'd assume) if the action has async code in it?

Answer 1

What are you searching is what is formatters in ASP.NET Core and how they work. From official documentation:

An action isn't required to return any particular type; MVC supports any object return value. If an action returns an IActionResult implementation and the controller inherits from Controller, developers have many helper methods corresponding to many of the choices. Results from actions that return objects that are not IActionResult types will be serialized using the appropriate IOutputFormatter implementation.

You also need to read about Content Negotiation :

Content negotiation only takes place if an Accept header appears in the request. When a request contains an accept header, the framework will enumerate the media types in the accept header in preference order and will try to find a formatter that can produce a response in one of the formats specified by the accept header. In case no formatter is found that can satisfy the client's request, the framework will try to find the first formatter that can produce a response (unless the developer has configured the option on MvcOptions to return 406 Not Acceptable instead).

and finally in scope of JsonResult using:

Actions can return specific results that are always formatted in a particular manner. For example, returning a JsonResult will return JSON-formatted data, regardless of client preferences.

Read more in Formatting Response Data section.