API REST de Fetcher

Ubícate en la API del Manager de Fetcher: autenticación bearer, alcance de producto, paginación, filtrado y la forma de error RFC 9457 que comparten las 12 operaciones.

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:

Authorization: Bearer <token>

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

---

Solo crear conexión, listar conexiones y la asignación de conexión leen X-Product-Name. Identifica el producto dueño de una conexión externa.

• 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, las conexiones almacenadas se acotan a un producto. Sin él, las conexiones almacenadas siguen dentro del alcance del tenant.
• La asignación de conexión lo exige. Los demás endpoints de conexión no consumen este header.

Un job nombra a su producto dueño en metadata.source, que es obligatorio. Para una conexión externa, ese valor debe coincidir con el producto de la conexión. Los datasources internos quedan fuera de esta comprobación.

​

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.

Parámetro	Valor por defecto	Reglas
page	1	Número de página. Debe ser 1 o mayor.
limit	10	Elementos por página. Debe ser 1 o mayor, y como máximo MAX_PAGINATION_LIMIT (100 tal como se distribuye).
sortOrder	desc	asc o desc. Fetcher siempre ordena por fecha de creación.
startDate	—	Límite temporal inferior inclusivo sobre la fecha de creación, analizado desde YYYY-MM-DD.
endDate	—	Límite temporal superior inclusivo, analizado a medianoche desde YYYY-MM-DD. No incluye el resto de ese día calendario; usa la fecha siguiente para cubrir un día final completo.

Una respuesta de página lleva items, page, limit y total.

{
  "items": [],
  "page": 1,
  "limit": 10,
  "total": 42
}

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.

En la página 1, los datasources internos definidos por entorno aparecen delante de las conexiones almacenadas y cuentan para total. Los filtros de producto, fecha de creación y metadata se aplican a las conexiones almacenadas; solo type filtra la lista interna.

​

Filtrado

---

El listado de conexiones acepta dos filtros más allá de la ventana de fechas.

• type — Fetcher normaliza el valor a mayúsculas y lo usa como filtro de igualdad. Un valor no reconocido normalmente no coincide con ninguna conexión almacenada; el parser no lo limita a cinco valores.
• 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.

{
  "type": "<problem-base-uri>/FET-0001",
  "title": "Bad Request",
  "status": 400,
  "detail": "empty request body",
  "code": "FET-0001",
  "errors": [
    { "location": "body.configName", "message": "is required" }
  ]
}

Campo	Qué lleva
type	Referencia URI a la documentación del problema codificado de Fetcher.
title	Texto de estado HTTP para este problema.
status	El código de estado HTTP.
detail	Explicación específica de esta ocurrencia.
instance	Referencia URI para esta ocurrencia específica.
code	Código de error de dominio estable, con la forma FET-NNNN.
errors	Detalles opcionales por campo con location y message; value es opcional.

Haz coincidir sobre code, no sobre title ni detail. Los códigos se agrupan por rango:

Rango	Significado	Ejemplos
FET-000x	Resultados generales	FET-0001 solicitud inválida, FET-0002 error interno, FET-0004 conflicto, FET-0005 no encontrado
FET-04xx	Problemas de solicitud	FET-0403 header inválido, FET-0405 parámetro de consulta inválido, FET-0406 límite de paginación excedido, FET-0414 host prohibido
FET-10xx	Reglas de negocio	FET-1002 conflicto de entidad, FET-1021 job en curso, FET-1040 conexión caída
FET-106x	Validación de esquema	FET-1060 validación fallida, FET-1062 objeto no encontrado

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.