aspnet-api-standards

Original：🇺🇸 English

Translated

ASP.NET Core Web API implementation: clean controllers with CQRS, global error handling, model validation, Swagger/OpenAPI, API versioning, security (CORS, auth), middleware pipeline, and performance patterns. Use when creating or editing controllers, filters, middleware, Program.cs, or API endpoints.

1installs

Sourceanalistadesarrollo4/skills

Added on2026-02-09

NPX Install

npx skill4agent add analistadesarrollo4/skills aspnet-api-standards

SKILL.md Content

View Translation Comparison →

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

csharp

// 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)

csharp

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:

csharp

builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderCommandValidator>();
builder.Services.AddFluentValidationAutoValidation();

aspnet-api-standards

NPX Install

Tags

SKILL.md Content

ASP.NET Core API Standards

CRITICAL DIRECTIVE

Core Controller Rules (ALWAYS Apply)

Clean Controllers Pattern

When to Read References

FluentValidation (Apply When Creating Commands/Queries)