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.
33 lines
1.4 KiB
Markdown
33 lines
1.4 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 added structure is justified.
|
|
- 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()`.
|
|
|
|
## 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.
|