Apéndice de la Web API
Referencia rápida de las convenciones transversales de la Web API de Crono. El detalle está en La Web API en detalle.
Tipo de medio
La API produce y consume exclusivamente:
application/vnd.crono.v1+json
Envía siempre las cabeceras Accept y Content-Type con ese valor; en caso contrario recibirás 415 Unsupported Media Type.
Autenticación
Todas las peticiones usan el esquema de autenticación Api y se autorizan por permiso ([Permiso(...)]). Ver Autenticación.
Códigos de estado
| Código | Significado |
|---|---|
200 OK | Operación correcta; devuelve el DTO. |
400 Bad Request | Error inesperado / solicitud mal formada. |
401 Unauthorized | Sin credencial válida. |
403 Forbidden | Autenticado pero sin permiso. |
404 Not Found | Recurso no encontrado. |
409 Conflict | Conflicto con el estado actual. |
412 Precondition Failed | Precondición no cumplida. |
415 Unsupported Media Type | Falta o es incorrecto el tipo de medio. |
422 Unprocessable Entity | El cuerpo no supera la validación de modelo. |
Modelo de errores
Los errores se devuelven de forma uniforme como problem details, a partir del tipo de error del dominio (ErrorTipo) que se traduce al código HTTP correspondiente. En una acción:
return Problema(new Error(ErrorTipo.Validacion, "El rango de fechas no es válido."));
Versionado
La versión va en la ruta (api/v1/...) y cada acción declara la versión con MapToApiVersion. Cada grupo de la documentación declara sus versiones. Ver Cambios de versión.
Grupos de documentación
Los grupos disponibles (WebApiGrupoNombres) son: finanzas, comun, configuracion, contenido, identidad, persona, prestamo, recursoshumanos, usuario, venta y plataforma. Cada controlador se asigna a uno con [WebApiGrupo(...)] para aparecer en su documento OpenAPI.
Convenciones de nombres
- Rutas en kebab-case y en plural cuando aplica:
rutas-cobranza,paradas/estado. - DTOs de entrada/salida con sufijo
Dto(RutaCobranzaDto,FuncionRutaDto). - Métodos asíncronos con
CancellationTokencomo último parámetro. - Respuestas tipadas documentadas con
[ProducesResponseType(typeof(...), Status200OK)].
Para un recorrido completo por un recurso real, ver el ejemplo de rutas de cobranza.