Back to: ASP.NET Core Web API Tutorials
Controller Action Return Types in ASP.NET Core Web API
In this article, I will discuss the different Controller Action Method Return Types in ASP.NET Core Web API Applications with Examples. Please read our previous article discussing Routing in ASP.NET Core Web API. At the end of this article, you will understand the different ways to return data from the ASP.NET Core Controller action method.
Controller Action Return Types in ASP.NET Core Web API
In ASP.NET Core Web API, controller actions can return various types of responses depending on the specific requirements of each endpoint to handle different scenarios and provide flexibility in how responses are sent to clients. Choosing the appropriate return type is crucial for managing HTTP responses effectively, ensuring type safety, and enhancing API documentation.
In ASP.NET Core Web API, controller action methods can return various types to manage HTTP responses effectively. The primary return types include:
- Primitive or Complex Types
- IActionResult
- ActionResult<T>
- Specific Result Types
- Task<IActionResult> or Task<ActionResult<T>>
Examples to Understand Action Return Types in ASP.NET Core Web API
Let us create a new ASP.NET Core Web API project called ReturnTypeAndStatusCodes.
Adding Employee Model:
Once you create the Project, add a folder named Models to the project root directory. Then, add a class file named Employee.cs to the Models folder and copy-paste the following code into it. This class contains ID, Name, Gender, City, Age, and Department properties.
namespace ReturnTypeAndStatusCodes.Models
{
public class Employee
{
public int Id { get; set; }
public string Name { get; set; }
public string Gender { get; set; }
public string City { get; set; }
public int Age { get; set; }
public string Department { get; set; }
}
}
Adding Employee Controller:
Then, add an empty ASP.NET Core Web API Controller named EmployeeController within the Controllers folder. Once you create the controller, it will be created with the following code.
using Microsoft.AspNetCore.Mvc;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
}
}
Returning Primitive or Complex Types from Controller Action Method
Controller action methods can directly return primitive types (e.g., int, string) or complex types (e.g., custom classes like Employee). By default, ASP.NET Core serializes these return values to JSON (or XML, depending on configuration) and sends them in the HTTP response body.
Returning Primitive Types
Primitive types are basic data types such as int, string, bool, etc. Returning a primitive type from an action method results in a simple JSON value in the response. For a better understanding, please modify the Employee Controller as follows. The GetName Action Method returns a string. You can return any primitive data from the ASP.NET Core Web API Controller action method.
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
[HttpGet("Name")]
public string GetName()
{
return "Return from GetName";
}
}
}
Now, run the application, and navigate to /api/employee/name URL, and you should get the following response.
Returning Complex Type:
Complex types are custom classes that contain multiple properties. Returning a complex type serializes the entire object into a JSON object. Now, let us see how to return complex employee data using the controller action method. We have already created the Employee model. Let us return an employee object from the controller action method. So, please modify the Employee Controller as follows.
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
[HttpGet("Details")]
public Employee GetEmployeeDetails()
{
return new Employee()
{
Id = 1001,
Name = "Anurag",
Age = 28,
City = "Mumbai",
Gender = "Male",
Department = "IT"
};
}
}
}
Now run the application and navigate to /api/employee/details URL, and you should get the following response. Here, you are getting the response in JSON format, which will return the employee data in a key-value pair.
Returning Collections
You can return collections of complex types, such as List<Employee> or IEnumerable<Employee>, which serialize to JSON arrays. Let us return the list of employees using the controller action method. So, please modify the Employee Controller as follows:
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
[HttpGet("All")]
public List<Employee> GetAllEmployees()
{
return new List<Employee>
{
new Employee { Id = 1001, Name = "Anurag", Age = 28, City = "Mumbai", Gender = "Male", Department = "IT" },
new Employee { Id = 1002, Name = "Pranaya", Age = 28, City = "Delhi", Gender = "Male", Department = "IT" },
new Employee { Id = 1003, Name = "Priyanka", Age = 27, City = "BBSR", Gender = "Female", Department = "HR" }
};
}
}
}
Now, run the application and navigate to /api/employee/all URL, and you should get the following response. Here, you get the list of employees as an array of JSON.
Alternative Return Type:
Instead of List<Employee>, you can use IEnumerable<Employee> for more flexibility. Please modify the Employee Controller as follows:
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
[HttpGet("All")]
public IEnumerable<Employee> GetAllEmployees()
{
return new List<Employee>
{
new Employee { Id = 1001, Name = "Anurag", Age = 28, City = "Mumbai", Gender = "Male", Department = "IT" },
new Employee { Id = 1002, Name = "Pranaya", Age = 28, City = "Delhi", Gender = "Male", Department = "IT" },
new Employee { Id = 1003, Name = "Priyanka", Age = 27, City = "BBSR", Gender = "Female", Department = "HR" }
};
}
}
}
Now run the application and navigate to /api/employee/all URL, and you should get the same response as the previous example.
Primitive or Complex Types Limitations:
When the response is simple and predictable, such as returning a value or a straightforward data object. For examples, Returning a calculated result (e.g., a number or string) or a small, consistent object. However, it comes with the following limitations:
- Lack of Control Over Status Code: We cannot explicitly set the HTTP status code, as the response defaults to 200 OK.
- No Error Handling Built-In: It does not support returning error codes or additional metadata like headers unless wrapped in a custom object or another mechanism.
- Limited Flexibility: Not suitable for scenarios where we may want to return different types of responses (e.g., success, error, or validation failure).
IActionResult Return Type in ASP.NET Core Web API:
IActionResult is an interface that allows controller actions to return various HTTP responses dynamically. It provides greater flexibility by enabling actions to return different HTTP status codes and response types based on runtime conditions. We will get the following Benefits from Using IActionResult.
- It allows actions to return different HTTP responses (e.g., Ok(), NotFound(), BadRequest()) from a single action method dynamically based on runtime conditions.
- It allows actions to control the exact response details, such as status codes, headers, and content.
- With IActionResult as the return type, we can easily handle and return error responses like StatusCode(500).
Note: IActionResult is an interface that defines a contract for the result of an action method. It allows for the return of any specific result types that implement the IActionResult interface, providing maximum flexibility.
Example: Returning IActionResult
Now, we want to return a list of employees from our action method. If at least one Employee is present, we need to return the status OK with the list of employees, and if no Employee is found, then we need to return the status code Not Found. If some error occurs while executing the application code, we need to return a 500 Internal Server error.
So, please modify the Employee Controller as shown below. Here, we created one action method, i.e., GetAllEmployees, with the return type IActionResult. The following code is self-explained, so please read the comment lines for a better understanding.
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
[HttpGet("All")]
//As we are going to return Ok, StatusCode, and NotFound Result from this action method,
//we are using IActionResult as the return type of this method
public IActionResult GetAllEmployee()
{
try
{
//In Real-Time, you will get the data from the database
//Here, we have hardcoded the data
var listEmployees = new List<Employee>()
{
new Employee(){ Id = 1001, Name = "Anurag", Age = 28, City = "Mumbai", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1002, Name = "Pranaya", Age = 28, City = "Delhi", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1003, Name = "Priyanka", Age = 27, City = "BBSR", Gender = "Female", Department = "HR"},
};
//If at least one Employee is Present return OK status code and the list of employees
if (listEmployees.Any())
{
return Ok(listEmployees);
}
else
{
//If no Employee is Present return Not Found Status Code
return NotFound();
}
}
catch (Exception ex)
{
// Log the exception
// Return a 500 Internal Server Error status code
return StatusCode(500, "An error occurred while processing your request.");
}
}
}
}
Possible Responses:
- 200 OK: Returns the list of employees.
- 404 Not Found: No employees found.
- 500 Internal Server Error: An error occurred during processing.
First, run the application and find the port number on which your application is running. We will use the Postman client tool to check the returned data with the HTTP Status Code. So, open Postman and make a GET HTTP Request to /api/employee/all endpoint. As you can see in the below image, we first select the HTTP Verb GET (1), provide the URL (2), and finally click on the Send button (3) to make a GET request to the URL we specified.
Once we hit the send button, you will get the following response. Notice that along with the employee data in JSON format, we are also getting a status code 200 OK here, as shown in the image below.
Returning Not Found Data using IActionResult in ASP.NET Core:
Please modify the Employee Controller as follows. Now, we have the GetEmployeeDetail Action method, which accepts the Employee ID as an input parameter and then returns that employee data. If the employee ID exists, then it will return the employee data. Otherwise, it will return Not Found data.
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
//As the following method is going to return Ok, Internal Server Error and NotFound Result
//So, we are using IActionResult as the return type of this method
[HttpGet("{Id}")]
public IActionResult GetEmployeeDetails(int Id)
{
try
{
//In Real-Time, you will get the data from the database, here, we have hardcoded the data
var listEmployees = new List<Employee>()
{
new Employee(){ Id = 1001, Name = "Anurag", Age = 28, City = "Mumbai", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1002, Name = "Pranaya", Age = 28, City = "Delhi", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1003, Name = "Priyanka", Age = 27, City = "BBSR", Gender = "Female", Department = "HR"},
};
//Fetch the Employee Data based on the Employee Id
var employee = listEmployees.FirstOrDefault(emp => emp.Id == Id);
//If Employee Exists Return OK with the Employee Data
if (employee != null)
{
return Ok(employee);
}
else
{
//If Employee Does Not Exists Return NotFound
return NotFound();
}
}
catch (Exception ex)
{
// Log the exception
// Return a 500 Internal Server Error status code
return StatusCode(500, "An error occurred while processing your request.");
}
}
}
}
With the above action method, run the application and send the following HTTP request (/api/employee/105) from the postman. As you can see, we are passing the employee ID as 105, which does not exist in our database.
Once you hit the Send button, you will get the following response. Notice, now we are getting a 404 Not Found response as the employee ID that we are sending does not exist.
When we use IActionResult as the return type to return multiple responses with different status codes, tools like Swagger may not infer the response types automatically, as shown in the image below.
As you can see in the above image, the kind of data the API will return is not displayed. To overcome the above problem and improve API documentation, we need to use the [ProducesResponseType] attribute to specify the possible HTTP responses and their types explicitly.
What is ProducesResponseType in ASP.NET Core Web API?
The ProducesResponseType attribute in ASP.NET Core Web API specifies the type of response and the HTTP status code that a particular action method can return. This attribute is useful for documenting API responses clearly and explicitly, making it easier for developers to understand what kind of responses to expect from an API endpoint.
The ProducesResponseType attribute can be applied multiple times to an action method to specify different possible responses. This is helpful for tools like Swagger/OpenAPI to generate accurate API documentation. For a better understanding, please modify the EmployeeController as follows:
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
[HttpGet("All")]
//As we are going to return Ok, StatusCode, and NotFound Result from this action method,
//we are using IActionResult as the return type of this method
//200 OK: Returns a list of Employee objects.
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(List<Employee>))]
//404 Not Found: Indicates that no employees were found.
[ProducesResponseType(StatusCodes.Status404NotFound)]
//500 Internal Server Error: Indicates an unexpected error during processing.
[ProducesResponseType(StatusCodes.Status500InternalServerError)]
public IActionResult GetAllEmployee()
{
try
{
//In Real-Time, you will get the data from the database
//Here, we have hardcoded the data
var listEmployees = new List<Employee>()
{
new Employee(){ Id = 1001, Name = "Anurag", Age = 28, City = "Mumbai", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1002, Name = "Pranaya", Age = 28, City = "Delhi", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1003, Name = "Priyanka", Age = 27, City = "BBSR", Gender = "Female", Department = "HR"},
};
//If at least one Employee is Present return OK status code and the list of employees
if (listEmployees.Any())
{
return Ok(listEmployees);
}
else
{
//If no Employee is Present return Not Found Status Code
return NotFound();
}
}
catch (Exception ex)
{
// Log the exception
// Return a 500 Internal Server Error status code
return StatusCode(500, "An error occurred while processing your request.");
}
}
//As the following method is going to return Ok, Internal Server Error and NotFound Result
//So, we are using IActionResult as the return type of this method
[HttpGet("{Id}")]
//200 OK: Returns an Employee object.
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Employee))]
//404 Not Found: Indicates that no employee is found.
[ProducesResponseType(StatusCodes.Status404NotFound)]
//500 Internal Server Error: Indicates an unexpected error during processing.
[ProducesResponseType(StatusCodes.Status500InternalServerError)]
public IActionResult GetEmployeeDetails(int Id)
{
try
{
//In Real-Time, you will get the data from the database, here, we have hardcoded the data
var listEmployees = new List<Employee>()
{
new Employee(){ Id = 1001, Name = "Anurag", Age = 28, City = "Mumbai", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1002, Name = "Pranaya", Age = 28, City = "Delhi", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1003, Name = "Priyanka", Age = 27, City = "BBSR", Gender = "Female", Department = "HR"},
};
//Fetch the Employee Data based on the Employee Id
var employee = listEmployees.FirstOrDefault(emp => emp.Id == Id);
//If Employee Exists Return OK with the Employee Data
if (employee != null)
{
return Ok(employee);
}
else
{
//If Employee Does Not Exists Return NotFound
return NotFound();
}
}
catch (Exception ex)
{
// Log the exception
// Return a 500 Internal Server Error status code
return StatusCode(500, "An error occurred while processing your request.");
}
}
}
}
Now, if you view the swagger, it must display the different responses based on the ProducesResponseType attribute, as shown in the image below.
IActionResult Limitations:
We need to use IActionResult when the action needs to return different types of HTTP status codes or result objects (e.g., Ok, NotFound, BadRequest). For example, a method that checks if a record exists and returns Ok with data or NotFound if the record does not exist. However, it comes with the following limitations:
- IActionResult doesn’t specify the data type returned, which can complicate API documentation and client-side deserialization. It may require extra effort to ensure consumers know what to expect.
ActionResult<T> Return Type in ASP.NET Core Web API:
ActionResult<T> is a generic return type that combines the flexibility of IActionResult with the type safety of returning a specific data type (T). It allows us to return either an ActionResult or a particular type (T) from our controller actions. That means we can return standard HTTP responses like NotFound() or BadRequest() or a specific data type when the operation is successful. The following are the Benefits of Using ActionResult<T>:
- Type Safety: Provides a strongly typed response, enhancing code readability and maintainability.
- Flexibility: Allows returning both specific data (T) and various HTTP status codes (ActionResult), such as NotFound(), BadRequest(), etc.
- Enhanced Documentation: Improves API documentation by explicitly declaring both the data model and potential action results.
Note: The ActionResult<T> is a generic class that inherits from ActionResult and implements IActionResult. It allows us to return either a specific type (T) or any result type, combining type safety with flexibility.
Example: Using ActionResult<T>
Let us understand this with an example. Please modify the Employee Controller class as shown below. This is the same example, but we have used the ActionResult<T> as the return type and removed the ProducesResponseType attribute.
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
[HttpGet("All")]
public ActionResult<List<Employee>> GetAllEmployee()
{
try
{
//In Real-Time, you will get the data from the database, here, we have hardcoded the data
var listEmployees = new List<Employee>()
{
new Employee(){ Id = 1001, Name = "Anurag", Age = 28, City = "Mumbai", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1002, Name = "Pranaya", Age = 28, City = "Delhi", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1003, Name = "Priyanka", Age = 27, City = "BBSR", Gender = "Female", Department = "HR"},
};
//If at least one Employee is Present return OK status code and the list of employees
if (listEmployees.Any())
{
return Ok(listEmployees);
}
else
{
//If no Employee is Present return Not Found Status Code
return NotFound();
}
}
catch (Exception ex)
{
// Log the exception
// Return a 500 Internal Server Error status code
return StatusCode(500, "An error occurred while processing your request.");
}
}
[HttpGet("{Id}")]
public ActionResult<Employee> GetEmployeeDetails(int Id)
{
try
{
//In Real-Time, you will get the data from the database, here, we have hardcoded the data
var listEmployees = new List<Employee>()
{
new Employee(){ Id = 1001, Name = "Anurag", Age = 28, City = "Mumbai", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1002, Name = "Pranaya", Age = 28, City = "Delhi", Gender = "Male", Department = "IT" },
new Employee(){ Id = 1003, Name = "Priyanka", Age = 27, City = "BBSR", Gender = "Female", Department = "HR"},
};
//Fetch the Employee Data based on the Employee Id
var employee = listEmployees.FirstOrDefault(emp => emp.Id == Id);
//If Employee Exists Return OK with the Employee Data
if (employee != null)
{
return Ok(employee);
}
else
{
//If Employee Does Not Exists Return NotFound
return NotFound();
}
}
catch (Exception ex)
{
// Log the exception
// Return a 500 Internal Server Error status code
return StatusCode(500, "An error occurred while processing your request.");
}
}
}
}
Specific Result Types in ASP.NET Core Web API
In ASP.NET Core, specific result types are concrete classes implementing the IActionResult interface. They represent particular HTTP responses with predefined status codes and, optionally, response bodies. That means they allow developers to return specific status codes and data. The Common Specific Result Types are as follows:
OkResult and OkObjectResult
- OkResult: Returns a 200 OK status without a body. It’s ideal when you want to indicate success but don’t need to return any data.
- OkObjectResult: Returns a 200 OK status with a response body. Use this when you want to return data along with a successful status.
NotFoundResult and NotFoundObjectResult
- NotFoundResult: Returns a 404 Not Found status without a body. It’s useful when the requested resource does not exist.
- NotFoundObjectResult: Returns a 404 Not Found status with a response body, typically with a message or additional details about why the resource was not found.
BadRequestResult and BadRequestObjectResult
- BadRequestResult: Returns a 400 Bad Request status without a body. It indicates that the request was malformed or incorrect.
- BadRequestObjectResult: Returns a 400 Bad Request status with a response body that includes error information, which can help the client understand what went wrong.
StatusCodeResult
- Allows us to return any HTTP status code with or without returning any data.
CreatedAtActionResult
- Returns a 201 Created status and includes a location header pointing to the newly created resource. It’s often used in POST methods that create a new resource.
NoContentResult
- It returns a 204 No Content status, indicating that the action was successful but that there is no additional information to return.
Each of these classes encapsulates a specific HTTP response, making returning consistent and meaningful responses from your API endpoints easier.
Example to Understand Specific Action Results
If an action method is guaranteed to return only one type of response (e.g., always 200 OK), you might return the specific result type directly for simplicity. To better understand, please modify the Employee Controller as follows.
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
// Static list of employees to simulate a data source
private static readonly List<Employee> Employees = new List<Employee>
{
new Employee { Id = 1, Name = "John Doe", Gender = "Male", City = "New York", Age = 30, Department = "HR" },
new Employee { Id = 2, Name = "Jane Smith", Gender = "Female", City = "Los Angeles", Age = 25, Department = "Finance" },
new Employee { Id = 3, Name = "Mike Johnson", Gender = "Male", City = "Chicago", Age = 40, Department = "IT" }
};
[HttpGet("all")]
public OkObjectResult GetAllEmployees()
{
// Return the list of employees with a 200 OK status
// OkObjectResult with data
return Ok(Employees);
}
}
}
Why Use IActionResult or ActionResult<T> Instead of Specific Result Types Directly?
An action method might need to return different HTTP responses based on business logic (e.g., 200 OK, 404 Not Found, 400 Bad Request). If you return a specific result type (e.g., OkObjectResult), you limit the method to that single response type unless you change the return type or use casting, which complicates the code.
In the below example, the method can return either NotFoundObjectResult or OkObjectResult based on the presence of the employee. Suppose you were to return a specific result type directly (e.g., always returning OkObjectResult). In that case, you’d lose the ability to return different responses without changing the method’s return type, and you will get a compile-time error, as shown in the below image:
By returning IActionResult or ActionResult<T>, we can dynamically return any specific result type as needed. For a better understanding, please modify the Employee Controller as follows:
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
// Static list of employees to simulate a data source
private static readonly List<Employee> Employees = new List<Employee>
{
new Employee { Id = 1, Name = "John Doe", Gender = "Male", City = "New York", Age = 30, Department = "HR" },
new Employee { Id = 2, Name = "Jane Smith", Gender = "Female", City = "Los Angeles", Age = 25, Department = "Finance" },
new Employee { Id = 3, Name = "Mike Johnson", Gender = "Male", City = "Chicago", Age = 40, Department = "IT" }
};
// Read (GET all employees)
// This action returns a list of all employees
[HttpGet("all")]
[ProducesResponseType(typeof(List<Employee>), 200)]
public OkObjectResult GetAllEmployees()
{
// Return the list of employees with a 200 OK status
// OkObjectResult with data
return Ok(Employees);
}
// Read (GET employee by ID)
// This action returns a single employee based on the provided ID
[HttpGet("{id}")]
public ActionResult<Employee> GetEmployeeById(int id)
{
// Find the employee with the specified ID
var employee = Employees.FirstOrDefault(e => e.Id == id);
if (employee == null)
{
// If the employee is not found, return a 404 Not Found status with a custom message
// NotFoundObjectResult with additional info
return NotFound(new { message = $"No employee found with ID {id}" });
}
// If the employee is found, return it with a 200 OK status
// OkObjectResult with the employee
return Ok(employee);
}
}
}
Asynchronous Return Types in ASP.NET Core Web API:
Asynchronous programming is essential for building scalable web applications. ASP.NET Core supports asynchronous action methods using return types like Task<IActionResult> and Task<ActionResult<T>>. This allows our action methods to perform asynchronous operations and return various responses.
Task<IActionResult> Return Type
In ASP.NET Core Web API, Task<IActionResult> is used for asynchronous action methods that return various HTTP responses. This approach is commonly used when the action method performs asynchronous operations. It combines two concepts: Task for asynchronous programming and IActionResult for flexible HTTP responses. So, it combines asynchronous programming with the flexibility of IActionResult.
This combination is useful when non-blocking I/O operations are required, such as when dealing with external web services, databases, or file systems. Based on runtime conditions, the action method wants to return different HTTP responses (Ok, NotFound, BadRequest, etc.).
Example: Using Task<IActionResult>
For a better understanding, please have a look at the following example, where we have used the Task<IActionResult> return type. The following example shows the asynchronous operations, and to simulate the same, we have delayed the execution by 1 second.
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
// Static list of employees to simulate a data source
private static readonly List<Employee> Employees = new List<Employee>
{
new Employee { Id = 1, Name = "John Doe", Gender = "Male", City = "New York", Age = 30, Department = "HR" },
new Employee { Id = 2, Name = "Jane Smith", Gender = "Female", City = "Los Angeles", Age = 25, Department = "Finance" },
new Employee { Id = 3, Name = "Mike Johnson", Gender = "Male", City = "Chicago", Age = 40, Department = "IT" }
};
// Read (GET all employees)
[HttpGet]
[ProducesResponseType(typeof(IEnumerable<Employee>), 200)]
[ProducesResponseType(500)]
public async Task<IActionResult> GetAllEmployees()
{
try
{
// Simulate an asynchronous operation
await Task.Delay(TimeSpan.FromSeconds(1));
// Return the list of employees with a 200 OK status
return Ok(Employees);
}
catch (Exception)
{
// Return 500 Internal Server Error in case of an exception
return StatusCode(500, "Internal server error");
}
}
// Read (GET employee by ID)
[HttpGet("{id}")]
[ProducesResponseType(typeof(Employee), 200)]
[ProducesResponseType(typeof(object), 404)]
[ProducesResponseType(typeof(object), 500)]
public async Task<IActionResult> GetEmployeeById(int id)
{
try
{
// Simulate an asynchronous operation
await Task.Delay(TimeSpan.FromSeconds(1));
// Find the employee with the specified ID
var employee = Employees.FirstOrDefault(e => e.Id == id);
if (employee == null)
{
// If the employee is not found, return a 404 Not Found status with a custom message
return NotFound(new { message = $"No employee found with ID {id}" });
}
// If the employee is found, return it with a 200 OK status
return Ok(employee);
}
catch (Exception)
{
// Return 500 Internal Server Error in case of an exception
return StatusCode(500, "Internal server error");
}
}
// Create (POST new employee)
[HttpPost]
[ProducesResponseType(typeof(Employee), 201)]
[ProducesResponseType(typeof(object), 400)]
[ProducesResponseType(typeof(object), 500)]
public async Task<IActionResult> CreateEmployee([FromBody] Employee employee)
{
try
{
// Simulate an asynchronous operation
await Task.Delay(TimeSpan.FromSeconds(1));
// Validate the employee data
if (employee == null || string.IsNullOrEmpty(employee.Name))
{
// If the data is invalid, return a 400 Bad Request status with a custom message
return BadRequest(new { Message = "Invalid employee data" });
}
// Assign a new ID to the employee
employee.Id = Employees.Count + 1;
// Add the employee to the list
Employees.Add(employee);
// Return a 201 Created status with a location header pointing to the newly created employee
return CreatedAtAction(nameof(GetEmployeeById), new { id = employee.Id }, employee);
}
catch (Exception)
{
// Return 500 Internal Server Error in case of an exception
return StatusCode(500, "Internal server error");
}
}
// Update (PUT existing employee)
[HttpPut("{id}")]
[ProducesResponseType(204)]
[ProducesResponseType(typeof(object), 400)]
[ProducesResponseType(404)]
[ProducesResponseType(500)]
public async Task<IActionResult> UpdateEmployee(int id, [FromBody] Employee employee)
{
try
{
// Simulate an asynchronous operation
await Task.Delay(TimeSpan.FromSeconds(1));
// Validate the employee data
if (employee == null || id != employee.Id)
{
// If the data is invalid, return a 400 Bad Request status with a custom message
return BadRequest(new { Message = "Invalid employee data" });
}
// Find the existing employee with the specified ID
var existingEmployee = Employees.FirstOrDefault(e => e.Id == id);
if (existingEmployee == null)
{
// If the employee is not found, return a 404 Not Found status
return NotFound();
}
// Update the employee properties
existingEmployee.Name = employee.Name;
existingEmployee.Gender = employee.Gender;
existingEmployee.City = employee.City;
existingEmployee.Age = employee.Age;
existingEmployee.Department = employee.Department;
// Return a 204 No Content status to indicate that the update was successful
return NoContent();
}
catch (Exception)
{
// Return 500 Internal Server Error in case of an exception
return StatusCode(500);
}
}
// Delete (DELETE employee)
[HttpDelete("{id}")]
[ProducesResponseType(200)] //No Data with 200 OK
[ProducesResponseType(404)] //No Data with 404 Not Found
[ProducesResponseType(500)] //No Data with 500 Internal Server Error
public async Task<IActionResult> DeleteEmployee(int id)
{
try
{
// Simulate an asynchronous operation
await Task.Delay(TimeSpan.FromSeconds(1));
// Find the employee with the specified ID
var employee = Employees.FirstOrDefault(e => e.Id == id);
if (employee == null)
{
// If the employee is not found, return a 404 Not Found status
return NotFound();
}
// Remove the employee from the list
Employees.Remove(employee);
// Return a 200 OK status with no content
return Ok();
}
catch (Exception)
{
// Return 500 Internal Server Error in case of an exception
return StatusCode(500);
}
}
}
}
Task<ActionResult<T>> Return Type in ASP.NET Core Web API:
In ASP.NET Core Web API, Task<ActionResult<T>> is a generic return type used for asynchronous action methods. It combines the benefits of asynchronous programming with the flexibility of the ActionResult<T> type, providing type-safe HTTP responses. It allows returning either an ActionResult or a specific type T asynchronously.
Example: Using Task<ActionResult<T>>
For a better understanding, please have a look at the following example, where we have used the Task<ActionResult<T>> return type.
using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;
namespace ReturnTypeAndStatusCodes.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class EmployeeController : ControllerBase
{
// Static list of employees to simulate a data source
private static readonly List<Employee> Employees = new List<Employee>
{
new Employee { Id = 1, Name = "John Doe", Gender = "Male", City = "New York", Age = 30, Department = "HR" },
new Employee { Id = 2, Name = "Jane Smith", Gender = "Female", City = "Los Angeles", Age = 25, Department = "Finance" },
new Employee { Id = 3, Name = "Mike Johnson", Gender = "Male", City = "Chicago", Age = 40, Department = "IT" }
};
// Read (GET all employees)
[HttpGet]
public async Task<ActionResult<List<Employee>>> GetAllEmployees()
{
try
{
// Simulate an asynchronous operation
await Task.Delay(TimeSpan.FromSeconds(1));
// Return the list of employees with a 200 OK status
return Ok(Employees);
}
catch (Exception)
{
// Return 500 Internal Server Error in case of an exception
return StatusCode(500, "Internal server error");
}
}
// Read (GET employee by ID)
[HttpGet("{id}")]
public async Task<ActionResult<Employee>> GetEmployeeById(int id)
{
try
{
// Simulate an asynchronous operation
await Task.Delay(TimeSpan.FromSeconds(1));
// Find the employee with the specified ID
var employee = Employees.FirstOrDefault(e => e.Id == id);
if (employee == null)
{
// If the employee is not found, return a 404 Not Found status with a custom message
return NotFound(new { message = $"No employee found with ID {id}" });
}
// If the employee is found, return it with a 200 OK status
return Ok(employee);
}
catch (Exception)
{
// Return 500 Internal Server Error in case of an exception
return StatusCode(500, "Internal server error");
}
}
// Create (POST new employee)
[HttpPost]
public async Task<ActionResult<Employee>> CreateEmployee([FromBody] Employee employee)
{
try
{
// Simulate an asynchronous operation
await Task.Delay(TimeSpan.FromSeconds(1));
// Validate the employee data
if (employee == null || string.IsNullOrEmpty(employee.Name))
{
// If the data is invalid, return a 400 Bad Request status with a custom message
return BadRequest(new { Message = "Invalid employee data" });
}
// Assign a new ID to the employee
employee.Id = Employees.Count + 1;
// Add the employee to the list
Employees.Add(employee);
// Return a 201 Created status with a location header pointing to the newly created employee
return CreatedAtAction(nameof(GetEmployeeById), new { id = employee.Id }, employee);
}
catch (Exception)
{
// Return 500 Internal Server Error in case of an exception
return StatusCode(500, "Internal server error");
}
}
// Update (PUT existing employee)
[HttpPut("{id}")]
public async Task<ActionResult> UpdateEmployee(int id, [FromBody] Employee employee)
{
try
{
// Simulate an asynchronous operation
await Task.Delay(TimeSpan.FromSeconds(1));
// Validate the employee data
if (employee == null || id != employee.Id)
{
// If the data is invalid, return a 400 Bad Request status with a custom message
return BadRequest(new { Message = "Invalid employee data" });
}
// Find the existing employee with the specified ID
var existingEmployee = Employees.FirstOrDefault(e => e.Id == id);
if (existingEmployee == null)
{
// If the employee is not found, return a 404 Not Found status
return NotFound();
}
// Update the employee properties
existingEmployee.Name = employee.Name;
existingEmployee.Gender = employee.Gender;
existingEmployee.City = employee.City;
existingEmployee.Age = employee.Age;
existingEmployee.Department = employee.Department;
// Return a 204 No Content status to indicate that the update was successful
return NoContent();
}
catch (Exception)
{
// Return 500 Internal Server Error in case of an exception
return StatusCode(500, "Internal server error");
}
}
// Delete (DELETE employee)
[HttpDelete("{id}")]
public async Task<ActionResult> DeleteEmployee(int id)
{
try
{
// Simulate an asynchronous operation
await Task.Delay(TimeSpan.FromSeconds(1));
// Find the employee with the specified ID
var employee = Employees.FirstOrDefault(e => e.Id == id);
if (employee == null)
{
// If the employee is not found, return a 404 Not Found status
return NotFound();
}
// Remove the employee from the list
Employees.Remove(employee);
// Return a 200 OK status with no content
return Ok();
}
catch (Exception)
{
// Return 500 Internal Server Error in case of an exception
return StatusCode(500, "Internal server error");
}
}
}
}
When Should We Use Which Return Type in ASP.NET Core Web API?
Choosing the appropriate return type depends on the specific requirements of your action method:
- Primitive or Complex Types: Use for simple, straightforward responses where detailed control over the response is not needed.
- IActionResult: We need to use IActionResult when we need to return different types of responses (e.g., success, error, not found) from a single action method.
- ActionResult<T>: We need to use ActionResult<T> to return a specific type of data along with the flexibility to return different HTTP status codes. This provides clear API documentation.
- Specific Result Types: We need to use specific result types when we want to be explicit about the kind of response returned, allowing direct control over the response type and status code.
- Task<IActionResult> or Task<ActionResult<T>>: These two return types are used for asynchronous action methods that perform I/O-bound operations like database calls, file I/O, or external service calls.
Understanding and appropriately using various controller action return types in ASP.NET Core Web API is essential for building robust, scalable, well-documented APIs. Whether you are returning simple data types, utilizing the flexibility of IActionResult, or combining type safety with ActionResult<T>, selecting the correct return type ensures that your API communicates effectively with clients. Additionally, using asynchronous programming for action methods performing I/O-Bound Operations further enhances the performance and usability of your web services.
In the next and a few upcoming articles, we will discuss the most useful Status Code Methods in ASP.NET Core Web API Applications. In this article, I try to explain Controller Action Method Return Types in ASP.NET Core Web API Application with examples. I hope you enjoy how to return different return types in the ASP.NET Core Web API Controller action methods article.
About the Author: Pranaya Rout
Pranaya Rout has published more than 3,000 articles in his 11-year career. Pranaya Rout has very good experience with Microsoft Technologies, Including C#, VB, ASP.NET MVC, ASP.NET Web API, EF, EF Core, ADO.NET, LINQ, SQL Server, MYSQL, Oracle, ASP.NET Core, Cloud Computing, Microservices, Design Patterns and still learning new technologies.
I wonder the Quality of these articles and yet no comments