Saltar a contenido

04. API (WebAPI)

La WebAPI es una aplicación Python FastAPI (título: "Aclimate v3 API", versión 3.0) que expone endpoints RESTful organizados por dominio funcional. Utiliza el paquete aclimate_v3_orm para el acceso a datos y proporciona autenticación basada en JWT mediante Keycloak.

URL Base

https://api.aclimate.org

La documentación de la API (Swagger UI) está disponible en https://api.aclimate.org/docs.

Autenticación

La API usa tokens JWT mediante Keycloak. Todos los endpoints (excepto health) requieren autenticación.

Flujo de Credenciales de Cliente

POST /auth/client-token
Content-Type: application/json

{
    "client_id": "...",
    "client_secret": "..."
}

Respuesta:

{
  "access_token": "eyJ...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Todas las solicitudes posteriores incluyen el token:

Authorization: Bearer <token>

Validación de Token

POST /auth/validate-token
Authorization: Bearer <token>

Dominios de la API

Dominio Tags Descripción
Geográfico Admin levels, Locations Países, divisiones admin, ubicaciones
Clima Climate Historical Daily/Monthly/Climatology/Indicator Datos climáticos históricos
Agronómico Indicators Indicadores, categorías, características
Auth Authentication Gestión de tokens
Usuarios Users Operaciones CRUD de usuarios
Roles Roles Gestión de roles
GeoServer Geoserver Acceso a datos espaciales
Health Health Verificaciones de salud del servicio

Convenciones de Endpoints

Todos los endpoints retornan respuestas JSON. Los endpoints de listado soportan los siguientes patrones comunes:

Formato de Respuesta

{
  "id": 1,
  "name": "Colombia",
  "iso2": "CO"
}

Manejo de Errores

Códigos de estado HTTP estándar:

  • 200: Éxito
  • 401: No autorizado (token faltante/inválido)
  • 403: Prohibido (permisos insuficientes)
  • 404: No encontrado
  • 422: Entidad no procesable
  • 500: Error interno del servidor

Respuestas de error:

{
  "detail": "Descripción del error"
}

Esquemas

La API utiliza esquemas Pydantic del directorio schemas/ para la serialización de solicitudes/respuestas. Los esquemas clave incluyen:

  • Country: id, name, iso2
  • Admin1: id, name, ext_id, country_id, country_name, country_iso2
  • Admin2: id, name, ext_id, admin1_id, admin1_name, country_id, country_name, country_iso2
  • Location: id, name, latitude, longitude, altitude, jerarquía admin, fuente
  • LocationWithData: Location + datos de monitoreo más recientes con medidas
  • MeasureData: measure_id, measure_name, measure_short_name, measure_unit, value
  • ClimateHistoricalDateRecord: location, measure, date, value
  • ClimateHistoricalMonthRecord: location, measure, month, value
  • ClimateHistoricalIndicatorRecord: indicator, location, value, period, rango de fechas
  • MinMaxMonthRecord / MinMaxDateRecord: valores mín/máx por ubicación

Endpoints de Salud

Endpoint Método Descripción
/health GET Verificación de actividad (Docker HEALTHCHECK)
/ready GET Verificación de preparación (sonda Kubernetes, verifica BD)

El endpoint de salud retorna {"status": "ok"} y el endpoint de preparación verifica la conectividad de la base de datos, retornando 200 si está saludable o 503 si no lo está.

Secciones