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.
39 lines
1.8 KiB
Markdown
39 lines
1.8 KiB
Markdown
---
|
|
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/v1` for 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 untyped `Results` for OpenAPI metadata inference.
|
|
- Return **`ProblemDetails`** (RFC 9457) for all error responses — configure via `AddProblemDetails()`.
|
|
|
|
## Authorisation
|
|
|
|
- Apply `.RequireAuthorization()` at the group level for protected resources.
|
|
- Reference policy names through `const string` fields 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 **`IValidatableObject`** to fail fast.
|
|
- Use **`CancellationToken`** on 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.
|