api-design-dotnet

API Design for .NET

Extends core/rules/api-design.mdc with .NET and ASP.NET Core specific patterns.

---

ASP.NET Core Controllers

Minimal APIs vs Controllers

// Minimal API (simple endpoints)
app.MapGet("/api/users/{id}", async (int id, IUserService service) =>
{
    var user = await service.GetUserAsync(id);
    return user is not null ? Results.Ok(user) : Results.NotFound();
});

// Controller (complex endpoints with multiple actions)
[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    private readonly IUserService _userService;

    [HttpGet("{id}")]
    [ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<ActionResult<UserDto>> GetUser(int id) { }
}

Action Return Types

• Use ActionResult<T> for typed responses
• Use IActionResult when returning multiple types
• Use Results helpers in Minimal APIs
• Document with [ProducesResponseType] attributes

---

MediatR CQRS Pattern

Commands and Queries

// Command (write operation)
public record CreateUserCommand(string Email, string Name)
    : IRequest<Result<UserId>>;

// Query (read operation)
public record GetUserQuery(int Id)
    : IRequest<Result<UserDto>>;

// Handler
public class CreateUserHandler : IRequestHandler<CreateUserCommand, Result<UserId>>
{
    public async Task<Result<UserId>> Handle(
        CreateUserCommand request,
        CancellationToken cancellationToken)
    {
        // Validation, business logic, persistence
    }
}

Benefits

• Clear separation of reads and writes
• Single responsibility per handler
• Easier to test in isolation
• Supports pipeline behaviors (logging, validation, caching)

---

FluentValidation

public class CreateUserCommandValidator : AbstractValidator<CreateUserCommand>
{
    public CreateUserCommandValidator()
    {
        RuleFor(x => x.Email)
            .NotEmpty()
            .EmailAddress()
            .MaximumLength(255);

        RuleFor(x => x.Name)
            .NotEmpty()
            .MinimumLength(2)
            .MaximumLength(100);
    }
}

// Register in DI
services.AddValidatorsFromAssemblyContaining<CreateUserCommandValidator>();

// Use in MediatR pipeline
services.AddTransient(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));