In ASP.NET Core, in addition to creating typical MVC applications, we can also create REST APIs. There are many rules that you need to remember in such a case, so that your applications are willingly used by customers. You will certainly write such REST APIs often in your career, it can be ideal, for example, as a backend for SPA applications, but not only. When creating such an application, it is worth remembering all the best practices. In this article, I will present you with 6 best practices for creating web applications in ASP.NET Core REST API, thanks to which your API will meet all the requirements.
1. Actions should return appropriate types and codes
According to convention, REST API controller actions should return types and codes. Actions from controllers can return type IActionResult and, depending on the response, an appropriate code.
HTTP codes:
- 100-199 informational response
- 200-299 success
- 300-399 redirect
- 400-499 client error
- 500-599 server error
Most commonly used HTTP codes:
- 200, 201, 204
- 301
- 400, 401, 403, 404, 405
- 500
We can return all these codes in ASP.NET REST API.
2. Use appropriate attributes for actions
In REST API we have several types of methods. However, the 4 most commonly used are GET, POST, PUT and DELETE. In ASP.NET Core, thanks to the attributes that we place above the name of the action, we can correctly mark its type.
For the GET action, it will be [HttpGet].
For the POST action, it will be [HttpPost].
For the PUT action, it will be [HttpPut].
For the DELETE action, it will be [HttpDelete].
3. Use proper naming for endpoints
Remember to use proper naming for rest api endpoints. This means that we use only nouns here, without any verbs.
Correct endpoints/URLs:
- GET /users (get users)
- GET /users/10 (get user)
- POST /users (add user)
- PUT /users (update user)
- DELETE /users (delete user)
- DELETE /users/role (delete user role)
In such a case, it is best to create controllers for WEB API with a plural name. Then you can easily build such endpoints.
However, you should not create endpoints shown below.
Incorrect endpoints/URLs:
- GET /getUsers
- GET /getUserById/10
- POST /users/addUser
- PUT /updateUser
- DELETE /delete/user
Only here we describe the names of endpoints, while the names of actions in controllers may already have different names and here you can use verbs.
4. Allow the client to use pagination, sorting and filtering of data
Remember that when you provide a list of some data via REST API, it is worth adapting it so that the client can download only the data that they actually need. That is, create an action so that based on the parameters passed to it, the client can immediately apply pagination and can download, for example, only data from a selected page, and not all data from the database. Similarly, allow them to sort and filter data by various properties. Thanks to this, the entire application will work much faster and can be properly optimized.
public class MethodParameters
{
public int PageNumber { get; set; }
public int PageSize { get; set; }
public string SearchTerm { get; set; }
public string OrderBy { get; set; }
}5. Versioning API
When creating REST API from the beginning, design it so that versioning is possible. This means that we want to provide users with various actions, endpoints at the same time for different versions. It is important that the REST API update does not break the operation of client applications that use, for example, an older version of our API. In ASP.NET Core, versioning is fully supported, so it is worth using it. All you need is a few lines of configuration and our API will be created in accordance with good principles.
https://localhost/api/v1/users
https://localhost/api/v2/users
https://localhost/api/v3/users
https://localhost/api/v4/users
6. Use Swagger
Swagger is also supported by ASP.NET Core and if we check the appropriate checkbox when creating a new ASP.NET CORE REST API project, then swagger with the default configuration will automatically be added to our application. Thanks to it, we can immediately create REST API documentation and enable other programmers who will use this API to test it more easily. It is worth adding Swagger to each project, it makes the programmer's life much easier.
ASP.NET Core School
If you are interested in topics related to creating professional web applications in ASP.NET Core, consider joining: ASP.NET Core School. This is an advanced, practical ASP.NET Core MVC + REST API training for C#/.NET Developers. The training consists of 14 extensive modules. In the training, we create a complete application in ASP.NET Core from the first lines of code to cloud implementation (more here).
