API Endpoints Concept

Introduction

Traditional controllers have been a staple in web development, but they may fall short when it comes to unit testing and maintainability. The Endpoints concept offers an alternative that can lead to better testability and organization. In this article, we will explore the Endpoints concept and discuss how the Ardalis.Endpoints library created by Ardalis can help you adopt this approach in your projects.

The source code for this tutorial can be found here.

Packages Used

• Ardalis.Endpoints
• Swagger
• AutoMapper
• EntityFrameworkCore

Creating Endpoints

With the Endpoints concept, you create a separate class for each endpoint, which makes it easier to test individual endpoints. Let’s examine the List endpoint as an example.

The List.cs file is located in the Endpoints folder:

public class List : BaseAsyncEndpoint
        .WithoutRequest
        .WithResponse<ListCompanyResponse>
{
  .........
}

Since the List endpoint does not have any request data, we use WithoutRequest. The endpoint has a response, so we use WithResponse<ListCompanyResponse>, which means when calling this endpoint, we will receive a ListCompanyResponse.

The List.ListCompanyResponse.cs file looks like this:

public class ListCompanyResponse: BaseResponse
{
    public ListCompanyResponse(Guid correlationId) : base(correlationId)
    {
    }

    public List<CompanyDto> Companies { get; set; }
    public int Count { get; set; }
}

This class contains the companies DTO and the count of these companies. Note that the file name is List.ListCompanyResponse.cs, and the endpoint file name is List.cs. Visual Studio will nest these files for better organization. For more information on nesting, refer to this article.

Implementing the List Endpoint

The HandleAsync method handles the endpoint and returns the appropriate data. First, we retrieve the list of companies with var companies = await _repository.ListAsync(cancellationToken);. Then, we use AutoMapper to convert the Entity Company object to the DTO Company object. Finally, we count the companies and include all the data in the response.

You can download the source code from here and run it locally to learn more. If you have any questions, feel free to contact the author on LinkedIn or Discord.

Conclusion

The Endpoints concept, combined with the Ardalis.Endpoints library, provides a more testable and maintainable alternative to traditional controllers. By creating separate classes for each endpoint, you can improve your project organization and streamline your development process. Give this approach a try in your projects and see the benefits firsthand.

Further Reading

If you’re interested in learning more about the Endpoints concept, the Ardalis.Endpoints library, or other related topics, check out the following resources:

1. Ardalis.Endpoints GitHub Repository
2. Common web application architectures
3. Clean up your .NET Controllers with ApiEndpoints

Feedback and Questions

We’d love to hear your thoughts on this tutorial! If you have any questions or suggestions for improvement, please don’t hesitate to reach out. You can leave a comment below, or you can contact us through the following channels:

1. Email: shady@shadynagy.com
2. Twitter: @ShadyNagy_
3. LinkedIn: Shady Nagy
4. GitHub: ShadyNagy

We’ll do our best to address any questions or concerns you may have. We look forward to hearing from you and helping you make the most of .NET Core API in your projects!