When working with a layered or Clean Architecture in .NET, one of the key aspects for maintaining cohesion and separation of concerns is understanding how the Application Layer communicates with the API Layer (or Web Layer in the case of an ASP.NET Core application).
In this article, we’ll explore:
📐 The Role of Each Layer (API vs Application)
🧠 How to Structure Communication Between Them
💡 Examples Using Handlers, DTOs, and MediatR
🧪 Best Practices for Testability and Decoupling
🏗️ Architectural Layers Overview
┌─────────────────────┐
│ API Layer │ ← HTTP Interface (Controllers, Endpoints)
└─────────────────────┘
↓
┌─────────────────────┐
│ Application Layer │ ← Use Cases, DTOs, Handlers
└─────────────────────┘
↓
┌─────────────────────┐
│ Domain Layer │ ← Entities, Business Rules, Interfaces
└─────────────────────┘
↓
┌─────────────────────┐
│ Infrastructure Layer│ ← Implementations, Persistence, Services
└─────────────────────┘
📤 1. Who Calls Whom?
The API Layer is responsible for receiving HTTP requests and forwarding them to use cases (Application Layer). The business logic does not live in the controller — it's encapsulated inside the Application Handlers.
📦 2. Creating a Use Case (Command Handler)
// Application/Orders/Commands/CreateOrderCommand.cs
public record CreateOrderCommand(string CustomerEmail, List<string> Items) : IRequest<Guid>;
// Application/Orders/Handlers/CreateOrderHandler.cs
public class CreateOrderHandler : IRequestHandler<CreateOrderCommand, Guid>
{
public async Task<Guid> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
{
// Business rules, validations, persistence via interface
var orderId = Guid.NewGuid(); // Simulated example
return await Task.FromResult(orderId);
}
}
🧠 We are using MediatR to orchestrate the flow between layers without direct coupling.
🌐 3. Calling Application from API
// API/Controllers/OrdersController.cs
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
private readonly IMediator _mediator;
public OrdersController(IMediator mediator)
{
_mediator = mediator;
}
[HttpPost]
public async Task<IActionResult> Create([FromBody] CreateOrderCommand command)
{
var orderId = await _mediator.Send(command);
return CreatedAtAction(nameof(GetById), new { id = orderId }, orderId);
}
[HttpGet("{id}")]
public IActionResult GetById(Guid id)
{
// You could use another query/handler here
return Ok(new { Id = id, Status = "Mocked Order" });
}
}
🔁 4. Summary Flow
[HTTP Request]
↓
[API Controller] → Receives and validates
↓
[Mediator.Send(command)]
↓
[Application Handler]
↓
[Domain + Business Rules]
↓
[Persistence Interface]
📌 5. DTO Separation
Avoid exposing domain models directly from the API. Use specific DTOs for input and output.
// API.DTOs
public record CreateOrderRequest(string CustomerEmail, List<string> Items);
[HttpPost]
public async Task<IActionResult> Create([FromBody] CreateOrderRequest request)
{
var command = new CreateOrderCommand(request.CustomerEmail, request.Items);
var orderId = await _mediator.Send(command);
return Ok(orderId);
}
🧪 6. Testability & Benefits
✅ Easily test Handlers independently of the API
✅ No ASP.NET Core dependency in Application Layer
✅ Each layer with a single responsibility
✅ Flexible for other interfaces (Blazor, Console, CLI, etc.)
🧭 7. Suggested Project Structure
/API
└── Controllers/
└── DTOs/
└── Program.cs
/Application
└── Orders/
├── Commands/
├── Queries/
├── Handlers/
└── Validators/
/Domain
└── Entities/
└── Interfaces/
/Infrastructure
└── Persistence/
└── Services/
✅ Conclusion
The communication between the API and the Application Layer in modern .NET should be clean, decoupled, and testable. By using MediatR, DTOs, and layered separation of responsibilities, you can:
Apply Clean Architecture in practice
Scale your application with confidence
Maintain readability and cohesion across layers
Perfeito! Você pode adicionar esses links de contato no final do artigo traduzido em inglês com o seguinte bloco:
🤝 Connect with Me
If you work with modern .NET and want to master architecture, C#, DevOps, or interoperability, let’s talk:
