ai-corporate-brain/standards/dotnet-api-standard.md

Estándar Corporativo para APIs .NET

Framework

• .NET 8 o superior.
• ASP.NET Core Web API.
• C# moderno.
• Nullable enable.
• Async/await obligatorio para operaciones I/O.

Arquitectura

Usar Clean Architecture con capas separadas:

• API
• Application
• Domain
• Infrastructure
• Tests

Responsabilidad por capa

API

• Controllers o Minimal APIs.
• Middlewares.
• Autenticación.
• Autorización.
• Swagger.
• Health checks.

Application

• Casos de uso.
• Commands.
• Queries.
• DTOs.
• Validaciones.
• Interfaces.

Domain

• Entidades.
• Value Objects.
• Reglas de negocio.
• Eventos de dominio.
• Interfaces de repositorio.

Infrastructure

• Entity Framework Core.
• Repositorios.
• DbContext.
• Servicios externos.
• Implementaciones técnicas.

Tests

• Unit tests.
• Integration tests.
• API tests.

Patrones recomendados

• CQRS cuando exista complejidad.
• Repository Pattern cuando ayude a separar dominio.
• Unit of Work si hay transacciones complejas.
• Mediator si se usa MediatR.
• Result Pattern para manejo controlado de respuestas.

Seguridad

• JWT Bearer cuando aplique.
• Autorización por roles o policies.
• Validación de entrada obligatoria.
• Protección contra SQL Injection.
• Protección contra IDOR.
• No exponer stack traces.
• No retornar entidades directamente.
• No guardar secretos en código.

Documentación

Toda API debe incluir:

• Swagger/OpenAPI.
• Descripción de endpoints.
• Ejemplos de request/response.
• Códigos de error.
• Modelo de autenticación.

Observabilidad

Debe incluir:

• Logging estructurado.
• Correlation ID.
• Health checks.
• Métricas.
• Trazabilidad de errores.

Testing

Mínimo requerido:

• Unit tests de servicios.
• Unit tests de validadores.
• Integration tests de endpoints críticos.
• Pruebas de autenticación y autorización.