ASP.NET Core API Standards
CRITICAL DIRECTIVE
ONLY implement what is explicitly requested. Do NOT add unrequested features like:
-
CORS configuration (unless asked for)
-
Swagger/OpenAPI setup (unless asked for)
-
Authentication/Authorization (unless asked for)
-
Rate limiting, caching, compression (unless asked for)
-
Additional middleware (unless asked for)
When user requests ONE thing (e.g., "create an exception filter"), implement ONLY that thing.
Core Controller Rules (ALWAYS Apply)
Clean Controllers Pattern
// REQUIRED structure [ApiController] [Route("api/[controller]")] public class OrdersController(IMediator mediator) : ControllerBase { [HttpPost] public async Task<IActionResult> CreateOrder( [FromBody] CreateOrderCommand command, CancellationToken cancellationToken) { var result = await mediator.Send(command, cancellationToken); return CreatedAtAction(nameof(GetOrder), new { id = result }, result); } }
MUST:
-
Inject ONLY IMediator (never repositories or domain services)
-
Use primary constructors
-
Include CancellationToken in all async methods
-
Apply [ApiController] attribute for automatic validation
NEVER:
-
Put business logic in controllers
-
Inject repositories directly
-
Use .Result , .Wait() , or .GetAwaiter().GetResult()
When to Read References
User asks about exception handling or error responses?
→ Read references/exception-handling.md
User asks about CORS, authentication, or authorization?
→ Read references/security.md
User asks about Swagger or API documentation?
→ Read references/swagger.md
User asks about middleware pipeline or Program.cs configuration?
→ Read references/middleware.md
FluentValidation (Apply When Creating Commands/Queries)
public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand> { public CreateOrderCommandValidator() { RuleFor(x => x.CustomerId).NotEmpty(); RuleFor(x => x.Items).NotEmpty().Must(items => items.Count <= 50); } }
Register in Program.cs:
builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderCommandValidator>(); builder.Services.AddFluentValidationAutoValidation();