La Web API en detalle

Esta página describe cómo está construida la Web API de Crono: el controlador base, el enrutado y versionado, la agrupación para la documentación, el tipo de medio y el modelo de errores.

El controlador base CronoApiController

Todos los controladores de API heredan de CronoApiController (en Crono.Web.Api, dentro de Crono.Web.Comun), que centraliza el comportamiento común:

[ApiController]
[ComprobarSistemaMantenimiento]
[RastreoActividad(Order = 100)]
[Produces(WebAyudante.ACCEPT_CRONO)]             // application/vnd.crono.v1+json
[EnableCors("WebApiCorsPolitica")]
[Authorize(AuthenticationSchemes = "Api")]
[IgnoreAntiforgeryToken]
[Route("api/v{version:apiVersion}/[controller]")]
public class CronoApiController : ControllerBase
{
    // ayudantes de error: Problema(Error), Problema(List<Error>)
}

De él heredan, entre otras cosas: comprobación de modo mantenimiento, rastreo de actividad, autenticación por esquema Api, política CORS, tipo de medio de Crono y el enrutado versionado.

Enrutado y versionado

Crono versiona la API con Asp.Versioning. La ruta incorpora la versión y cada acción declara a qué versión responde:

[ApiVersion("1")]
[Route("api/v{version:apiVersion}/rutas-cobranza")]
public class RutasCobranzaController : CronoApiController
{
    [HttpGet("funciones"), MapToApiVersion("1")]
    public Task<IActionResult> ObtenerFunciones(CancellationToken ct) { /* ... */ }
}

Así conviven versiones distintas del mismo recurso (/api/v1/..., /api/v2/...) sin romper a los clientes existentes.

Agrupación para la documentación

Cada controlador se asigna a un grupo con [WebApiGrupo(...)], lo que determina bajo qué documento OpenAPI aparece en Swagger. Los grupos disponibles (WebApiGrupoNombres) son: finanzas, comun, configuracion, contenido, identidad, persona, prestamo, recursoshumanos, usuario, venta y plataforma. Cada grupo declara sus versiones (por ejemplo, comun expone 1 y 2).

[WebApiGrupo(WebApiGrupoNombres.Prestamo)]   // aparece en el documento "prestamo1"

Tipo de medio

La API produce y consume exclusivamente application/vnd.crono.v1+json (constante WebAyudante.ACCEPT_CRONO). Los clientes deben enviar Content-Type y Accept acordes; de lo contrario reciben 415 Unsupported Media Type.

Modelo de errores

Los errores se devuelven de forma uniforme como problem details. El controlador base traduce el tipo de error del dominio al código HTTP correspondiente:

Tipo de error (ErrorTipo)	Código HTTP
NoAutorizado	401
Prohibido	403
NoEncontrado	404
Conflicto	409
PrecondicionFallida	412
MedioTipoNoSoportado	415
Validacion	422
Inesperado	400

En una acción, devolver un error es tan simple como:

if (algoNoValida)
    return Problema(new Error(ErrorTipo.Validacion, "El rango de fechas no es válido."));

return Ok(resultado);

La validación de modelo se aplica automáticamente (atributo de validación de modelo de API), devolviendo 422 con el detalle de los campos inválidos.

Respuestas tipadas

Documenta el contrato de cada acción con [ProducesResponseType(...)], para que Swagger genere el esquema de la respuesta:

[ProducesResponseType(typeof(List<FuncionRutaDto>), Status200OK)]

Con esto, el controlador base y estos atributos garantizan que todos los endpoints compartan autenticación, versionado, formato y manejo de errores coherentes. Los ejemplos concretos por recurso están en la subsección de ejemplos.