| 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
- Ler
../../docs/architecture/architecture-baseline.md.
- Ler
../../docs/api-patterns/input-output-models.md.
- Ler
../../docs/api-patterns/route-parameters.md.
- 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
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
