ASP.NET Core and Web API

In the past I’ve looked at ServiceStack for developing REST services however there are alternatives to ServiceStack, one of which is Web Api. Let’s create a simple starter project using ASP.NET Core and Web Api to implement our services.

  • Create a new ASP.NET Core Web Application
  • Select API

The generated service supplies a Controllers/ValuesController.cs file which includes a controller class with the various REST methods.

Controllers partition your application’s API, so for example you might have an AuthenticateController solely for authentication methods and another controller for CRUD operations on a datasource.

For example this is a simple AuthenticateController class 

[Route("[controller]")]
[ApiController]
public class AuthenticateController : ControllerBase
{
   [HttpPost]
   public ActionResult<AuthenticateReponse> Post([FromBody] User user)
   {
      return new AuthenticateReponse
      {
         Token = $"{user.Name}|1234"
      };
   }
}

Here, the Route is set to [controller] so our URL would be http://localhost/Authenticate. In this example we intend for the user to send data within an HTTP POST method, passing a User object (which is a simple name/password object). An AuthenticateResponse object is return via the ActionResult.

The ActionResult return value allows us to return HTTP 200 OK or using subclasses such as BadRequest for an HTTP 400 and there are other derivations for other HTTP responses.

The Action<> allows us to return a 200 OK without the need of using the Ok() method, although this can be used if preferred.

When using different return responses it’s good to also document these by adding 

[ProducesResponseType(400)]

This indicates that the method may return an HTTP 400. This is useful for use with Open API tools such as Swagger.

As can be seen in the Post method, the User object is expected within the method’s body and the HttpPost attribute declare the method uses HTTP POST, the method name is superfluous in terms of the REST API.

The different HTTP methods

The code generated by the template creates a ValuesController with various HTTP methods, which I’ll recreate here for reference

HTTP GET without URL parameters

[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
   return new string[] { "value1", "value2" };
}

HTTP GET with URL parameters

[HttpGet("{id}")]
public ActionResult<string> Get(int id)
{
   return "value";
}

HTTP POST without URL parameters

[HttpPost]
public void Post([FromBody] string value)
{
}

HTTP PUT with URL parameters

[HttpPut("{id}")]
public void Put(int id, [FromBody] string value)
{
}

HTTP DELETE with URL parameters

[HttpDelete("{id}")]
public void Delete(int id)
{
}

HTTP HEAD

[HttpGet, HttpHead]
public IActionResult Head()
{
   return Ok();
}

We would request the headers using HttpHead along with an HttpGet.

HTTP PATCH

[HttpPatch]
public IActionResult Patch()
{
   return Ok();
}

Adding Swagger support

As per ASP.NET Core Web API help pages with Swagger / OpenAPI we can add Swagger support using either Swashbuckle.AspNetCore or NSwag (there may be others). Both are simple to add to our project.