.NET Naming Best Practises: API Models

API models are one of the elements where I personally see the most naming errors - which have a massive impact on the architect and cause subsequent errors. The solution is very simple: follow the naming rules!

Contrary to what you see in some documentation, API models do belong to the family of DTOs, but they have one major factor: models differ depending on whether they are used for the request or the response. And this is where you see most errors: models are used for both requests and responses - sometimes with massive consequences.

API models for requests

A basic rule for any type of model is that only the properties that are required for the respective purpose should exist. However, this is where you often see the mistake that models for requests also contain properties that are only required for the response. This leads to unnecessary data transfers and can lead to security vulnerabilities / architecture mistakes.

Example: creating a user.

1/// Don't do this!
2public class UserDTO
3{
4    public int UserId { get; set; }
5    public string UserName { get; set; }
6}

Here we see a (wrong) user DTO that has a property for the ID in addition to the user name. This example can be seen regularly in various documentations - not only in .NET. The problem is that the ID is not required for the request. It is generated by the server and returned in the response. The request should therefore only contain the user name.

1/// Do this!
2public class UserCreateRequestModel
3{
4    public string UserName { get; set; }
5}

Another difference is: if I separate my models into request and response models, I have the option of dealing with property values much better and more granularly in the case of requests, e.g. through optional properties and validations. This is a factor that is required in many real applications, but is not taken into account in documentation due to its simplicity.

API models for responses

The rule for responses is simple: only include the properties that are actually required. A request model can either be generic, because it is contained in several responses or specific to a use case.

 1/// Do this!
 2public class UserModel
 3{
 4    public int UserId { get; set; }
 5    public string UserName { get; set; }
 6}
 7
 8// or if you have a special model for the create response
 9public class UserCreateResponseModel
10{
11    public int UserId { get; set; }
12    public string UserName { get; set; }
13}

Summary: every API should have seperate Request- and Response-Models.

Validation

Another major advantage of this separation is that each model can be structured and set up separately and the validation - e.g. using FluentValidation - can also be set up individually.

This makes implementation much easier, especially in medium-sized and large applications.