aspnet-api-patterns

ASP.NET Core API Patterns

Reference for API development on ASP.NET Core 10. Authentication setup lives in skills/authentication/SKILL.md; the Result → HTTP mapping and ProblemDetails details live in skills/error-handling/SKILL.md.

Controller vs Minimal API Decision

Controller Pattern

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class UsersController(IUserService userService) : ControllerBase
{
    [HttpGet("{id:int}")]
    [ProducesResponseType(typeof(UserResponse), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<IActionResult> GetById(int id, CancellationToken ct)
    {
        var user = await userService.GetByIdAsync(id, ct);
        return user is null ? NotFound() : Ok(user);
    }

    [HttpPost]
    [ProducesResponseType(typeof(UserResponse), StatusCodes.Status201Created)]
    [ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> Create(CreateUserRequest request, CancellationToken ct)
    {
        var user = await userService.CreateAsync(request, ct);
        return CreatedAtAction(nameof(GetById), new { id = user.Id }, user);
    }
}

OpenAPI

.NET 9+ ships document generation in Microsoft.AspNetCore.OpenApi; Swashbuckle is no longer in the templates.

builder.Services.AddOpenApi();

if (app.Environment.IsDevelopment())
    app.MapOpenApi();          // serves /openapi/v1.json