Controllers and HTTP responses

Controller-based API

• In the previous Lecture 1, we created a rudimentary controller-based web API in ASP.NET
  • See also Create web APIs with ASP.NET Core
  • Note: It's also possible to create minimal APIs without controllers in ASP.NET
• Let's delve deeper into controllers that return HTTP responses with specific HTTP status codes
  • For a primer on HTTP status codes, check Frontend basics: Lecture 2

Controllers

• Controllers are classes that derive from the ControllerBase class
• In the project template, we had this controller:

  [ApiController]
  [Route("[controller]")]
  public class WeatherForecastController : ControllerBase
  

• ControllerBase provides many properties and methods for handling HTTP requests
• Inside the class, we can create methods that correspond to different endpoints (see Lecture 1: Routing and endpoints)
  • These are called result methods

Result methods

• Result methods return ActionResult objects
  • For example, a CreatedAtAction returns the 201 status code
  • All ActionResult objects implement the IActionResult interface
  • Includes at least a status code, and can contain data such as view items or an error message
• This result is processed into a response to then sent to client
• There are multiple possible status codes for each action (See the following table)

Some result methods

Result methods: An example

[HttpGet("{id}")]
public IActionResult GetContactById(int id)
{
  // Contacts = list of contact objects, fetched from some repository
  var contact = Contacts.FirstOrDefault(c => c.Id == id);
  if (contact == null)
  {
    return NotFound();
  }
  return Ok(contact);
}

• The previous code first attempts to find a Contacts object using the ID provided in the URI parameter
  • If an item is not found, a 404 response is returned using NotFound()
    
  • Otherwise, the object is sent as a payload with a 200 OK code response using Ok(contact)