api-backend-dotnet

name	api-backend-dotnet
description	Guia base para construir e evoluir backends HTTP em .NET 8 ou 10. Use quando a tarefa envolver controllers, pipeline HTTP, Program.cs, DI, middleware global de excecao, OpenAPI, boundary de API, input/output models, use cases, presenters ou convencoes de entrega de endpoints.

API Backend .NET 8/10

Quando usar esta skill

Use quando a tarefa envolver:

• criacao ou alteracao de endpoints;
• controllers e action methods;
• Program.cs, DI e pipeline HTTP;
• middleware global de excecao;
• OpenAPI, Swagger ou Scalar;
• boundary entre controller, use case e presenter.

Baseline default

• API controller-first.
• Controllers finos.
• Use case como orquestrador.
• InputModel para body.
• Dados de rota e contexto separados do body.
• Resposta padronizada no pipeline HTTP, quando adotada.

Antes de implementar

1. Ler ../../docs/architecture/architecture-baseline.md.
2. Ler ../../docs/api-patterns/input-output-models.md.
3. Ler ../../docs/api-patterns/route-parameters.md.
4. Ler ../../docs/api-patterns/api-response-format.md se o projeto usar resposta padronizada.

Regras de implementacao

Controllers

• Extrair [FromBody], [FromRoute], query e contexto separadamente.
• Chamar o use case com parametros explicitos.
• Evitar regra de negocio, SQL ou chamada externa direta no controller.
• Nao montar ApiResponse<T> manualmente quando o pipeline ja faz isso.

Use cases

• Um objetivo claro por caso de uso.
• Receber InputModel, rota/contexto e CancellationToken separadamente.
• Chamar ports/adapters e presenter quando o projeto usar esse padrao.

OpenAPI

• Documentar endpoints publicos ou integrados.
• Nao deixar endpoint novo sem contrato visivel.

Erros

• Preferir middleware global para padronizar excecao e status code.
• Evitar espalhar payload de erro manual por controller.

Checklist rapido

• controller fino
• body e rota separados
• validacao no boundary
• use case orquestrando
• OpenAPI atualizado
• testes cobrindo fluxo feliz e erros principais

Nao usar esta skill como desculpa para

• introduzir minimal API como default sem decisao explicita;
• colocar regra de negocio no controller;
• ignorar convencoes de tracking e story do pacote;
• misturar concerns HTTP, negocio e infraestrutura no mesmo arquivo.

Docs complementares

• ../../docs/architecture/architecture-baseline.md
• ../../docs/architecture/usecase-pattern.md
• ../../docs/architecture/presenter-pattern.md
• ../../docs/examples/complete-feature-example.md