Template
akritikos
8e3b5ebdfc
Introduces detailed instructions for ASP.NET API, C#, Docker, MSBuild, testing, and library creation. These guidelines aim to standardize development practices and improve code quality across the project.
1.4 KiB
1.4 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 added structure is justified.
- 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().
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.