Skip to content

API REST

El servidor expone una interfaz de programación de aplicaciones (API) basada en los principios de REST, utilizando JSON como formato de intercambio y códigos de estado HTTP estándar para la gestión de errores.

Endpoints expuestos

POST /discovery

Recibe los metadatos de los dotfiles desconocidos y crea una tarea de clasificación. Si todas las aplicaciones ya son conocidas por el servidor, las resuelve y devuelve instantáneamente. Si hay algún elemento desconocido, encola la tarea para su procesamiento asíncrono.

  • Response: 200 OK.
  • Payload: Objeto JSON con el taskID, el status de la tarea, y el mapa data (que será null si la tarea ha sido encolada en estado QUEUE).
GET /task/

Consulta el estado de una tarea previamente encolada.

  • Response: 200 OK.
  • Payload: Objeto JSON con el taskId, el status, el batchId y la clave data con el JSON resultante (si ha finalizado).
GET /health

Endpoint de comprobación de salud del sistema.

  • Response: 200 OK.
  • Payload: Texto plano "ok".

Formato de peticiones y respuestas

Ejemplo de Petición (POST /discovery)

El cliente envía una lista de rutas y sus tipos. Utiliza identificadores temporales como claves (ej. item_temporal_1):

{
  "data": {
    "item_temporal_1": { "path": ".op", "type": "folder" },
    "item_temporal_2": { "path": ".config/custom_app", "type": "folder" }
  }
}

Ejemplos de Respuesta POST /discovery

El servidor procesa la petición de forma asíncrona. Si detecta elementos desconocidos, encola el análisis y devuelve una respuesta con el estado de la tarea en cola. En caso de que todos los elementos ya fuesen previamente conocidos por la base de datos, resuelve y entrega la información de forma inmediata.

Caso A: Con elementos desconocidos (Estado QUEUE)

Si se encuentra al menos una ruta desconocida (ej. .config/custom_app), se encola una tarea asíncrona para análisis con Gemini. El servidor devuelve el identificador de la tarea y el estado QUEUE con el mapa data como nulo:

{
  "taskID": "TASK-Z1X2Y3W4V5U6",
  "status": "QUEUE",
  "data": null
}

Nota de diseño: El cliente detecta el estado QUEUE, extrae el taskID e inicia un sondeo periódico (polling) mediante GET /task/{id} hasta que el estado pase a COMPLETE.

Caso B: Todos los elementos son conocidos (Estado COMPLETE)

Si el servidor ya conoce todas las rutas recibidas, no requiere invocar la API de IA. Crea la tarea directamente en estado COMPLETE y devuelve toda la información de inmediato:

{
  "taskID": "TASK-A7B8C9D0E1F2",
  "status": "COMPLETE",
  "data": {
    "1password_cli": {
      "app_name": "1Password CLI",
      "category": "Security",
      "subcategory": "Password Manager",
      "files_info_json": [
        {
          "path": ".op",
          "type": "folder"
        }
      ],
      "packages_json": [
        "1password-cli"
      ],
      "ignored": false
    }
  }
}

Ejemplos de Respuesta GET /task/{id} (Sondeo / Polling)

El cliente realiza peticiones de tipo sondeo a /task/{id} para comprobar el estado de la clasificación. El formato de la respuesta en los diferentes estados de la tarea es el siguiente:

1. Tarea en cola (QUEUE)

La tarea ha sido registrada pero el programador en segundo plano de Spring aún no la ha tomado para su ejecución.

{
  "id": "TASK-Z1X2Y3W4V5U6",
  "status": "QUEUE",
  "batchId": null,
  "data": null
}
2. Tarea en proceso (PROCESSING)

El backend ha tomado la tarea y ha iniciado la petición de lote (Batch API) con Gemini. Ya dispone del identificador de lote de la API (batchId), pero el análisis sigue en curso.

{
  "id": "TASK-Z1X2Y3W4V5U6",
  "status": "PROCESSING",
  "batchId": "batches/batch_job_9988776655",
  "data": null
}
3. Tarea completada con éxito (COMPLETE)

El análisis asíncrono de la IA ha finalizado. El servidor actualizó la base de datos local y guardó el resultado estructurado de las nuevas aplicaciones identificadas.

{
  "id": "TASK-Z1X2Y3W4V5U6",
  "status": "COMPLETE",
  "batchId": "batches/batch_job_9988776655",
  "data": {
    "my_custom_app": {
      "app_name": "Mi App Personalizada",
      "category": "Development",
      "subcategory": "Editor",
      "files_info_json": [
        {
          "path": ".config/custom_app",
          "type": "folder"
        }
      ],
      "packages_json": [
        "custom-app-cli"
      ],
      "ignored": false
    }
  }
}
4. Tarea con error (ERROR)

Si ocurre algún fallo crítico e insalvable durante el procesamiento de la IA (de red, comunicación o datos corruptos), la tarea se marca con estado ERROR.

{
  "id": "TASK-Z1X2Y3W4V5U6",
  "status": "ERROR",
  "batchId": null,
  "data": null
}