All examples

ASP.NET Core Web API

Minimal-API service on .NET 10 with PostgreSQL, typed results, problem details, and policy-based authorization.

Composed from the aspnet-web-api rules pack. Same file from the CLI: aibysitter init --packs aspnet-web-api --format agents

Written for this site, CC0, scored by this linter, not tested against any agent.

File

AGENTS.md, 38 lines

Format

AGENTS.md

Save as

AGENTS.md

Category

.NET

Tags

• C#
• Web API
• PostgreSQL
• OpenAPI
• xUnit

License

CC0 1.0, public domain. No attribution needed.

Download AGENTS.md Lint a copy

Badge

Markdown for a README:

[![Aibysitter lint score: A 100](https://aibysitting.net/gallery/aspnet-web-api/badge.svg)](https://aibysitting.net/Gallery/aspnet-web-api)

AGENTS.md

View rendered

# ASP.NET Core web API

ASP.NET Core minimal APIs on .NET 10. PostgreSQL through EF Core and Npgsql. OpenAPI document generated at runtime.

## Commands
- Build: `dotnet build -warnaserror`
- Test: `dotnet test`
- Run: `dotnet run --project src/<App>.Api` (listens on `http://localhost:5080`)
- OpenAPI document: `GET /openapi/v1.json` while the API is running

## Endpoints
- Group endpoints by resource in `src/<App>.Api/Endpoints/<Resource>Endpoints.cs` with a `Map<Resource>Endpoints` extension method.
- Request and response types are records in `Contracts/`. Entities never leave the data layer.
- Return `TypedResults` (`Ok`, `Created`, `NotFound`, `ValidationProblem`) and declare them in the handler's return type.
- Validation failures return 400 with `ValidationProblem` and one error per field.
- Unknown IDs return 404 with an empty body.
- Routes are lowercase plural nouns: `/items`, `/items/{id}`, `/items/{id}/movements`.

## Errors
- Unhandled exceptions become RFC 9457 problem details through `app.UseExceptionHandler()`. Handlers do not catch exceptions to return 500 themselves.
- Optimistic-concurrency failures throw `ConflictException`. The exception handler maps it to 409.

## Data
- `<App>DbContext` lives in `src/<App>.Data`.
- Bulk changes use `ExecuteUpdateAsync` and `ExecuteDeleteAsync`.

## Authorization
- Every endpoint requires a policy: `.RequireAuthorization(Policies.Read)` or `.RequireAuthorization(Policies.Write)`.
- `/health` is the only endpoint with `AllowAnonymous`.

## Tests
- Integration tests in `tests/<App>.Api.Tests` use `WebApplicationFactory<Program>` and a Testcontainers PostgreSQL instance.
- Each new endpoint gets four tests: success, 400 on invalid input, 404 on an unknown ID, 403 without the required policy.
- Test names follow `Method_Condition_Result`.

## Pull requests
- One endpoint or one bug fix per PR.
- Add a line to `CHANGELOG.md` under the Unreleased heading.

1. # ASP.NET Core web API
3. ASP.NET Core minimal APIs on .NET 10. PostgreSQL through EF Core and Npgsql. OpenAPI document generated at runtime.
5. ## Commands
6. - Build: `dotnet build -warnaserror`
7. - Test: `dotnet test`
8. - Run: `dotnet run --project src/<App>.Api` (listens on `http://localhost:5080`)
9. - OpenAPI document: `GET /openapi/v1.json` while the API is running
11. ## Endpoints
12. - Group endpoints by resource in `src/<App>.Api/Endpoints/<Resource>Endpoints.cs` with a `Map<Resource>Endpoints` extension method.
13. - Request and response types are records in `Contracts/`. Entities never leave the data layer.
14. - Return `TypedResults` (`Ok`, `Created`, `NotFound`, `ValidationProblem`) and declare them in the handler's return type.
15. - Validation failures return 400 with `ValidationProblem` and one error per field.
16. - Unknown IDs return 404 with an empty body.
17. - Routes are lowercase plural nouns: `/items`, `/items/{id}`, `/items/{id}/movements`.
19. ## Errors
20. - Unhandled exceptions become RFC 9457 problem details through `app.UseExceptionHandler()`. Handlers do not catch exceptions to return 500 themselves.
21. - Optimistic-concurrency failures throw `ConflictException`. The exception handler maps it to 409.
23. ## Data
24. - `<App>DbContext` lives in `src/<App>.Data`.
25. - Bulk changes use `ExecuteUpdateAsync` and `ExecuteDeleteAsync`.
27. ## Authorization
28. - Every endpoint requires a policy: `.RequireAuthorization(Policies.Read)` or `.RequireAuthorization(Policies.Write)`.
29. - `/health` is the only endpoint with `AllowAnonymous`.
31. ## Tests
32. - Integration tests in `tests/<App>.Api.Tests` use `WebApplicationFactory<Program>` and a Testcontainers PostgreSQL instance.
33. - Each new endpoint gets four tests: success, 400 on invalid input, 404 on an unknown ID, 403 without the required policy.
34. - Test names follow `Method_Condition_Result`.
36. ## Pull requests
37. - One endpoint or one bug fix per PR.
38. - Add a line to `CHANGELOG.md` under the Unreleased heading.