api-pattern-dotnet

API pattern — .NET

Consistency is the point: the same kind of work looks the same everywhere, so the reviewer and the next agent read it without re-learning. You do not invent structure — you locate the codebase's canonical example and replicate it. This skill assumes Clean Architecture + CQRS via MediatR; the depth is in .claude/rules/clean-architecture.md.

Procedure

1. Find the canonical example. If the spec names one under "Reuse this pattern," read it. Otherwise grep for the nearest sibling of the same shape and pick the most recent, most-tested one — not the oldest. Useful anchors:

   • a command: Grep for : IRequest<Result< and IRequestHandler<
   • a validator: Grep for : AbstractValidator<
   • a controller action / minimal-API endpoint of the same verb
   • the layer's DependencyInjection.cs

2. Extract the pattern, don't paraphrase it. Note, from the example:

   • Layering — controller/endpoint → MediatR command → handler → repository/service.
   • The request/response types — IRequest<Result<TResponse>>; DTOs init-only; collections IReadOnlyList<T> on the surface.
   • Validation — a AbstractValidator<TRequest> discovered by assembly scan, run by the ValidationBehavior (never called inside the handler).
   • Error model — Result<T>.Success/Fail/ValidationFailure, not thrown exceptions, for expected failures.
   • DI — how it's registered (keyed vs standard) in DependencyInjection.cs.
   • The test shape — xUnit MethodName_Scenario_ExpectedResult, WebApplicationFactory + in-memory DB for the pipeline test.

3. Replicate exactly for the new surface — same naming, same file organization (one class per file, under the right layer), same immutability and boundary-validation conventions. Wire DI the same way. <ImplicitUsings> and <Nullable> are already enabled — write nullable-clean code.

4. Add the matching tests in the same style as the example's tests, including the failing-first test if this is a bug fix. Hit the 80% floor on the new code.