Skip to main content
El Manager sirve la API HTTP de Fetcher. Lleva 12 operaciones en dos áreas:
  • Jobs de extracción bajo /v1/fetcher — crear un job, leer un job.
  • Conexiones bajo /v1/management/connections — el ciclo de vida de la conexión, las lecturas de esquema, las pruebas de conexión y las dos operaciones de asignación de producto.
Las 12 operaciones se renderizan bajo el anclaje Fetcher en la Referencia de API. Esta página cubre lo que esas operaciones comparten. No repite sus formas de solicitud y respuesta.
Los documentos OpenAPI de este portal son fuentes de renderizado para las páginas de referencia. No son contratos de cliente, ni una base para generar SDKs.

​
Autenticación

Fetcher acepta un token bearer JWT:
La autenticación es una decisión de despliegue. PLUGIN_AUTH_ENABLED activa el middleware de autenticación, y PLUGIN_AUTH_ADDRESS lo apunta al servicio de identidad. El Manager se niega a arrancar cuando activas la autenticación y dejas la dirección vacía. El modo multi-tenant también requiere autenticación efectiva — el router se niega a construir un middleware de tenant sin ella. Consulta Configuración. Cada una de las 12 operaciones declara 401 y 403. Fetcher autoriza cada solicitud contra la aplicación fetcher, un recurso (connections o fetcher) y una acción que corresponde al método HTTP. Cinco rutas quedan fuera de la autenticación para que las sondas sigan funcionando: /health, /readyz, /readyz/tenant/{id}, /metrics y /version.

​
Alcance de producto

Las operaciones de conexión llevan un header X-Product-Name. Nombra el producto dueño de la conexión.
  • Crear una conexión lo exige. Fetcher rechaza un valor ausente, vacío o compuesto solo de espacios.
  • Listar conexiones lo trata como opcional. Con el header, ves las conexiones de un solo producto. Sin él, ves todas las conexiones dentro del alcance.
  • Fetcher pasa el valor a minúsculas. Acepta letras, dígitos, guiones bajos y guiones, hasta 100 caracteres.
Los jobs de extracción no usan este header. Un job nombra a su producto dueño en metadata.source, que el payload de creación exige.

​
Jobs asíncronos

POST /v1/fetcher responde 202 Accepted y devuelve un identificador de job con estado pending. El Worker ejecuta la extracción después de la respuesta. Fetcher deduplica las solicitudes de job por un hash de solicitud dentro de una ventana de 5 minutos. Una solicitud duplicada dentro de esa ventana responde 200 OK y devuelve el job existente en lugar de encolar un segundo. Un job que ya falló no impide un reintento — puedes reenviarlo. Para seguir un job, consulta GET /v1/fetcher/{id} de forma periódica, o suscríbete a los eventos terminales que describe Eventos de job.

​
Paginación

Ambas operaciones de listado — conexiones y conexiones sin asignar — usan paginación por offset con los mismos parámetros de consulta. Una respuesta de página lleva items, page, limit y total.
Una solicitud de listado siempre aplica una ventana de fecha de creación. Si no envías startDate ni endDate, Fetcher aplica el último mes hasta mañana. Las conexiones más antiguas quedan fuera de esa ventana. Define ambas fechas cuando quieras una vista más amplia.MAX_PAGINATION_MONTH_DATE_RANGE limita el ancho de esa ventana a un mes tal como se distribuye. Si pides un rango más amplio, Fetcher adelanta startDate para ajustarse al límite. No responde con un error.
Los datasources internos — los que un operador configura con las variables de entorno DATASOURCE_{NAME}_* — aparecen solo en la página 1, delante de las conexiones almacenadas, y cuentan para total.

​
Filtrado

El listado de conexiones acepta dos filtros más allá de la ventana de fechas.
  • type — uno de POSTGRESQL, MYSQL, ORACLE, SQL_SERVER o MONGODB. Fetcher pasa el valor a mayúsculas.
  • metadata.<key>=<value> — una coincidencia exacta sobre una entrada de metadata que guardaste con la conexión. Por ejemplo, metadata.region=br.
El listado de conexiones sin asignar se acota solo por la ventana de fechas. Responde una sola pregunta — qué conexiones siguen sin producto — así que no toma filtro de tipo ni de metadata. Fetcher ignora un parámetro de consulta desconocido en lugar de fallar la solicitud. Tres casos aún fallan con FET-0405:
  • Una clave que empieza con $, lo que bloquea la inyección de operadores de consulta.
  • Una clave que empieza con _, lo que bloquea los campos internos.
  • Una clave de más de 64 caracteres, o un valor de más de 256 caracteres.

​
Errores

Cada error responde application/problem+json y sigue RFC 9457.
Haz coincidir sobre code, no sobre title ni detail. Los códigos se agrupan por rango: Fetcher redacta los fallos a nivel de driver en su frontera. Descarta el error crudo de la base de datos, así que una cadena de conexión, una credencial o un detalle interno del driver nunca llega a un llamador.

​
Leer la especificación desde un Manager en ejecución

SWAGGER_ENABLED=true monta una referencia Scalar en /swagger/docs y el documento OpenAPI 3.1 en /swagger/openapi.json y /swagger/openapi.yaml. Mantenlo apagado en producción.

​
Próximos pasos

Referencia de API

Las 12 operaciones, con las formas completas de solicitud y respuesta.

Eventos de job

Reacciona a job.completed y job.failed en lugar de consultar de forma periódica.

Conceptos centrales

Conexiones, descubrimiento de esquemas, jobs de extracción, filtros y resultados.

Configuración

Las variables de entorno detrás de la autenticación, los límites de paginación y la superficie de API.