C_SHARP_SKILLS/.ai/skills/14-minimal-api-web-services.md

Skill 14 - Minimal API Web Services and HTTP Clients

Minimal API Rules

• Use Minimal APIs for concise HTTP endpoints, especially small services and focused APIs.
• Group related endpoints.
• Name endpoints where useful for link generation and OpenAPI clarity.
• Keep endpoint handlers thin; delegate business logic to services.
• Validate input before processing.
• Return typed results when practical.

OpenAPI Rules

• Generate OpenAPI documentation for public/internal APIs that clients consume.
• Add summaries, descriptions, response metadata, and XML comments where useful.
• Keep OpenAPI output accurate after route or DTO changes.

DTO Rules

• Use request and response DTOs.
• Do not expose EF entities directly.
• Make contracts explicit and version them when clients depend on them.

HTTP Client Rules

• Use IHttpClientFactory for outbound HTTP calls.
• Configure named or typed clients for external services.
• Set timeouts and resilience policies where appropriate.
• Pass cancellation tokens.
• Do not create and dispose HttpClient repeatedly in hot paths.

API Reliability

• Add health checks for deployable services.
• Log failures with context but no secrets.
• Use consistent error responses.
• Consider native AOT only after checking compatibility with reflection, serialization, and dependencies.