How to make an API with dotnet core

The goal of this post is to explain the purposes of the most important stuff going on in the process of creating an API for a blog. One consideration before starting is that I'm using netcore 2.2 at the moment of writing this post. If you use netcore 3.0 or higher, you are going to have a different controller created from scratch but the explanation on what the annotations mean is the same.

Initializing the project:

1. Let's create the project:

dotnet new webapi -n BlogApi

1. Create .sln file:

dotnet new sln -n BlogApi
dotnet sln add BlogApi/BlogApi.csproj

1. Create respective folders for unit tests and integration tests (we are going to put hands on this within the upcoming posts):

dotnet new xunit -n BlogApi.UnitTests
dotnet new xunit -n BlogApi.IntegrationTests
dotnet sln add BlogApi.UnitTests/BlogApi.UnitTests.csproj
dotnet sln add BlogApi.IntegrationTests/BlogApi.IntegrationTests.csproj

1. We are going to delete wwwroot since we won’t be going to use it. If you are using an IDE like Rider, you can just delete the folder, but if you are using Visual Studio Code you need to remove the reference from BlogApi.csproj.

<ItemGroup>
  <Folder Include="wwwroot\" />
</ItemGroup>

1. We are now ready to start putting hands on. Let’s go to the ValuesController.

[Route("api/[controller]")]
public class ValuesController : Controller

Before declaring the class, we have this Route annotation. In case you don’t know what it means, it is the route where you can access that controller. For example, in this case, we have:

[Route("api/[controller]")]

So, to access that controller you must go to:

http://whatever-your-url.com/api/values

And here, the important thing that we're interested in is /api/values. You can notice there that [controller] is a variable defined by NetCore and it is going to get the name of the controller. For example, if you have “PostsController” then, in this case, [controller] = posts. But, you can always define the route yourself as for example: [Route("this-is-my-route")] then your endpoint to access this controller will be:

http://whatever-your-url.com/this-is-my-route

Let’s go to our methods.

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

The first method begins with [HttpGet], which is the verb of the method. Therefore, we can also have: [HttpGet], [HttpPost], [HttpPut], [HttpDelete], [HttpPatch] and [HttpOptions].

What if we want to specify the explicit action in the url?

In this case, we can add a parameter to this annotation with the “name”. If we have [HttpGet("my-action")] then to access this method we have to go to:

http://whatever-your-url.com/api/values/my-action

Also, we could have [HttpGet("[action]")] (as we have with [controller]) and then it will take the name of the method. For example, let’s take the original example again:

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

To have access to it, we need to go to:

http://whatever-your-url.com/api/values/get

Lastly, we could receive variables to our methods included an object.

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

In this example, we have [HttpPut("{id}")] whatever goes between curly brackets is a variable, so here we have to make a PUT request to:

http://whatever-your-url.com/api/values/1

Being in this case, id = 1. In addition, we can also send objects in the body of the request. In this case, to access the body we need [FromBody] as well as [FromQuery] to access whatever we send in the querystring.

That’s it! If you have any doubt don’t hesitate to leave your comments or ask me ​​via Twitter.