Template
akritikos
eea4ce7a0e
Refines conventions for ASP.NET API endpoints, C# documentation, Docker build arguments, MSBuild package management, and testing method naming and structure. These changes aim to enhance clarity and enforce best practices across the codebase.
1.8 KiB
1.8 KiB
description
| description |
|---|
| Use when writing API endpoints, routing, middleware, request/response handling, OpenAPI configuration, or HTTP pipeline setup in ASP.NET. Covers Minimal API conventions, error handling, and endpoint organisation. |
ASP.NET API Conventions
Routing
- All endpoints live under
/api/v{apiVersion}/{resource}. - Default to
/api/v1for projects without explicit API versioning.
Endpoints
- Prefer Minimal APIs; use Controllers only when the endpoint group requires action filters, model binding customisation, or exceeds 10 endpoints sharing significant cross-cutting logic.
- Group related endpoints using
MapGroup()with a shared prefix and tag. - Use typed results (
TypedResults.Ok(),TypedResults.NotFound()) over untypedResultsfor OpenAPI metadata inference. - Return
ProblemDetails(RFC 9457) for all error responses — configure viaAddProblemDetails().
Authorisation
- Apply
.RequireAuthorization()at the group level for protected resources. - Reference policy names through
const stringfields on a shared static class (e.g.,.RequireAuthorization(AuthorizationPolicies.RequireAdminRole)) instead of inline string literals. - Mark public endpoints explicitly with
.AllowAnonymous().
Request Handling
- Bind request data with
[AsParameters]for complex parameter sets. - Validate input at the endpoint boundary — use filters or
IValidatableObjectto fail fast. - Use
CancellationTokenon all async endpoints.
Endpoint Organisation
- One file per resource or feature area (e.g.,
UserEndpoints.cs,OrderEndpoints.cs). - Register via extension methods on
IEndpointRouteBuilder:MapUserEndpoints(). - Keep endpoint lambdas thin — delegate business logic to injected services.
OpenAPI
- Annotate endpoints with
.WithTags()for grouping in the generated spec.