Making ASP.NET Core 3 web API return REST compliant Http return codes

To make an ASP.NET Web Api (core 3+) return valid Http status codes such as 200 OK, 400 Bad request and 404 Not found, use the IActionResult as return type.

Return code 422 can be used instead of 400, read more here: HTTP Status Codes For Invalid Data: 400 vs. 422

Code example C# web API controller “data” endpoint method:

/// <summary>
/// Get data from API
/// </summary>
/// <remarks>
/// GET: api/v1/data?id={id}
/// </remarks>
/// <returns><see cref="IActionResult"/> <see cref="Data"/>Data model</returns>
/// <response code="200">Serialized <see cref="Data"/></response>
/// <response code="400">Invalid id</response>
/// <response code="404">Found no match for id</response>
[ProducesResponseType(typeof(Data), 200)]
[ProducesResponseType(typeof(object), 400)]
[ProducesResponseType(typeof(object), 404)]
[HttpGet("data")]
public IActionResult GetData(string id)
{
    var data = business.GetData(id);
    if (data == null)
    {
        return NotFound(null); //404 not found
    }
    if (data.IsValid)
    {
        return Ok(data); //200 OK, found
    }
    else
    {
        return BadRequest(data.ValidationErrorMessage); //400 bad reqeust validationerror
    }
}

IActionResult type

The IActionResult return type is appropriate when multiple ActionResult return types are possible in an action. The ActionResult types represent various HTTP status codes. Any non-abstract class deriving from ActionResult qualifies as a valid return type. Some common return types in this category are BadRequestResult (400), NotFoundResult (404), and OkObjectResult (200). Alternatively, convenience methods in the ControllerBase class can be used to return ActionResult types from an action. For example, return BadRequest(); is a shorthand form of return new BadRequestResult();.

Because there are multiple return types and paths in this type of action, liberal use of the [ProducesResponseType] attribute is necessary. This attribute produces more descriptive response details for web API help pages generated by tools like Swagger[ProducesResponseType] indicates the known types and HTTP status codes to be returned by the action.

More info:
Controller action return types in ASP.NET Core web API | Microsoft Docs
HTTP Status Codes For Invalid Data: 400 vs. 422

Leave a Reply