Building a Web API with C# Records for DTOs

This blog article explores the use of C# records for Data Transfer Objects (DTOs) in ASP.NET Core Web API development. It offers insights into the benefits and practical application of C# records, using a UserController example to showcase how these immutable structures enhance data transfer operations in web APIs.

What are DTOs?

Data Transfer Objects (DTOs) are akin to the trustworthy couriers of your digital empire. These specialized objects serve a vital purpose in facilitating the exchange of data between different components of your application. But what exactly are DTOs, and why are they crucial?

Data Transfer Objects, or DTOs for short, are lightweight, container-like structures designed to transport data between different parts of your application. They act as intermediaries, shielding your core business entities (models) from external influences.

The Role of DTOs

Now, you might wonder, why not use the raw business entities for data transfer? Well, that's where DTOs step in. They serve several important functions.

Data Transformation: DTOs allow you to shape data into a format suitable for the client or consumer of your API. This transformation might involve flattening complex object hierarchies, excluding sensitive information like user identifiable properties, or even combining data from multiple sources.
Efficiency: By selectively including only the necessary information, DTOs can reduce the amount of data transferred over the network, optimizing the performance of your API.
Decoupling: They foster loose coupling between the client and server, enabling you to modify the underlying business entities without affecting the external interfaces.

When to Use DTOs?

While DTOs are invaluable, they're not required in every API scenario. You should consider employing them.

You need to shield your core business logic from external components.
Data must be customized for presentation or compatibility reasons.
There's a requirement to reduce data transfer overhead for performance optimization.
You want to enhance the maintainability and flexibility of your API.

Data Transfer Objects are the behind-the-scenes guardians ensuring secure and efficient communication, enabling your application to thrive in the ever-evolving digital landscape. Now that we've grasped the essence of DTOs, let's move on to harnessing C# records for these essential messengers in the subsequent sections of our journey.

Setting up the environment

Prerequisites

To begin, you'll require the following.

ASP.NET Core: Think of this as your kitchen, the heart of your application. ASP.NET Core provides the foundation for building web APIs.
Database Context: Your data storage, which acts like a well-organized pantry. Ensure you have a database context set up to interact with your data storage.

Defining Entities and DTOs

Now, let's create a simplified model. In our culinary metaphor, this is like setting up the recipe ingredients.

We'll define a User entity to represent our data.
For data transfer, we'll introduce a UserDTO as our Data Transfer Object. These are like the serving platters we'll use to present our dishes.

With these in place, we're ready to start cooking up our API using C# records to streamline the process.

// User class representing a database entity
public class User
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
}

// UserDTO record for data transfer
public record UserDTO(string FirstName, string LastName, string Email);

In your project, create User.cs and UserDTO.cs for these definitions.

In this code

The User class defines a database entity with properties for Id, FirstName, LastName, and Email. This class represents the structure of the data in your database.
The UserDTO record is a lightweight, immutable structure used for data transfer. It includes properties for FirstName, LastName, and Email. By using a record, you ensure that the data in this object cannot be modified once it's created, making it suitable for transferring data between different parts of your application.

Pros of Using Records

Immutability by Design: C# records are inherently immutable, meaning the data they hold cannot be modified after creation. This characteristic enhances data integrity and safety, particularly valuable when dealing with DTOs. It's like sealing your digital messages in an impenetrable envelope; once the data is inside, it remains unchanged.
Value-Based Equality: Records come with built-in value-based equality comparisons, making it easier to determine if two instances of a record hold the same data. This simplifies operations like comparing DTOs, ensuring that your data transfers are precise and reliable.
Conciseness and Clarity: The concise syntax of records eliminates a substantial amount of boilerplate code typically found in regular classes. This brevity leads to cleaner and more readable code, reducing the chances of errors and enhancing code maintainability.

Cons of Using Records

Limited Customization: While the default behaviors of records are advantageous, they also come with limited customization options. For more complex DTOs that require custom property accessors, serialization logic, or validation, records might fall short.
Immutability Constraints: The immutability enforced by records may not be suitable for every scenario. In some cases, you may need to modify data in-place, which is not the natural strength of records.
Compatibility Considerations: C# records were introduced in C# 9. If you are working with code or libraries that do not support C# 9 and later, you may encounter compatibility issues when using records in your application.

Handling HTTP Operations in Web API with C# Records

Let's dive into how you can employ C# records for Data Transfer Objects (DTOs) in your API, using an example of a UserController to illustrate these operations.

The UserController Class

Here's the UserController class, a central piece of your API, equipped to handle HTTP operations. In this example, we use C# records to facilitate data transfer between clients and your application. This controller defines methods for creating, retrieving, and deleting user resources.

[ApiController]
[Route("api/users")]
public class UserController : ControllerBase
{
    private readonly ApplicationDbContext _context;

    public UserController(ApplicationDbContext context)
    {
        _context = context;
    }

    [HttpPost]
    public async Task<IActionResult> CreateUser(UserDTO userDTO)
    {
        var user = new User
        {
            FirstName = userDTO.FirstName,
            LastName = userDTO.LastName,
            Email = userDTO.Email
        };

        _context.Users.Add(user);
        await _context.SaveChangesAsync();

        return CreatedAtAction("GetUser", new { id = user.Id }, user);
    }

	[HttpPut("{id}")]
    public async Task<IActionResult> UpdateUser(int id, UserDTO userDTO)
    {
        var user = await _context.Users.FindAsync(id);

        if (user == null)
        {
            return NotFound();
        }

        user.FirstName = userDTO.FirstName;
        user.LastName = userDTO.LastName;
        user.Email = userDTO.Email;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException)
        {
            // Handle concurrency conflicts if necessary.
            // For simplicity, this example does not include concurrency handling.
        }

        return NoContent();
    }

    [HttpGet]
    public async Task<ActionResult<IEnumerable<User>> GetUsers()
    {
        var users = await _context.Users.ToListAsync();
        return Ok(users);
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<User>> GetUser(int id)
    {
        var user = await _context.Users.FindAsync(id);

        if (user == null)
        {
            return NotFound();
        }

        return Ok(user);
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteUser(int id)
    {
        var user = await _context.Users.FindAsync(id);

        if (user == null)
        {
            return NotFound();
        }

        _context.Users.Remove(user);
        await _context.SaveChangesAsync();

        return NoContent();
    }
}

The UserController class demonstrates the practical benefits of C# records for data transfer. Records provide a concise and immutable means of structuring data, promoting clarity and precision in API operations. They safeguard data integrity and offer a reliable way to transport information between your application's components.

As you embark on your API development endeavors, consider the UserController example as a blueprint for efficient and clean HTTP operations. Leveraging C# records, you can build APIs that offer a seamless and reliable experience for clients and developers alike.