Resumen de API

Gigantics proporciona endpoints de API REST que permiten acceso programático a conjuntos de datos y pipelines sin requerir autenticación de UI. Esto permite integración con sistemas externos, flujos de trabajo automatizados y consumo de datos por aplicaciones.

Endpoints Disponibles

Endpoints de Conjunto de Datos

Descarga datos de conjunto de datos en varios formatos usando solicitudes GET:

GET /api/{org}/{proj}/model/{model}/dataset/{id}

Características:

• Múltiples formatos de salida (SQL, JSON, CSV, Oracle Loader)
• Filtrado de entidades
• Acceso a metadatos
• Limitación de registros

Ver Asignación de Endpoints de API para detalles.

Endpoints de Pipeline

Activa la ejecución de pipeline usando solicitudes POST:

POST /api/{org}/{proj}/model/{model}/pipeline/{id}

Características:

• Ejecución de trabajo asíncrona
• Seguimiento de estado de trabajo vía URL de trabajo retornada
• Integración con orquestadores externos

Ver Asignación de Endpoints de API para detalles.

Endpoint de Estado de Trabajo

Verifica el estado de trabajos (accesible públicamente, no requiere autenticación):

GET /api/job/{jobId}

Retorna:

• Estado del trabajo (ejecutándose, completado, falló)
• Porcentaje de progreso para trabajos en ejecución
• Razones de falla para trabajos fallidos
• Datos de resultado para trabajos completados

Autenticación

Todos los endpoints de conjunto de datos y pipeline requieren autenticación de clave API. Se soportan dos métodos:

1. Parámetro de consulta: ?api_key={tu-clave}
2. Cabecera Authorization: Authorization: Bearer {tu-clave}

Las claves API se crean y gestionan a través de la UI. Ver Autenticación para detalles.

Comenzando

1. Crea una clave API: Navega a Proyecto → Claves API y crea una clave
2. Asigna a un recurso: Haz clic en el ícono de compartir en un conjunto de datos o pipeline
3. Obtén la URL del endpoint: La URI se muestra en la UI
4. Haz solicitudes: Usa la clave API con la URL del endpoint

Conceptos Clave

Endpoints vs Recursos

• Recursos (conjuntos de datos, pipelines) son los datos/flujos de trabajo reales
• Endpoints son las URLs de API que exponen recursos
• Un recurso puede tener un endpoint
• Múltiples claves API pueden asignarse a un endpoint

Claves API

• Formato: {prefix}-{key} (31 caracteres total)
• Se muestra solo una vez durante la creación
• Puede estar activa o inactiva
• Almacenada como hashes bcrypt

Múltiples Claves por Endpoint

Puedes asignar múltiples claves API a un solo endpoint, permitiendo:

• Rotación de claves sin tiempo de inactividad
• Control de acceso multi-partido
• Claves de respaldo

Cualquier clave asignada autenticará el endpoint. Ver Múltiples Claves API por Endpoint para detalles.

Documentación

• Asignación de Endpoints de API - Crear y gestionar endpoints
• Múltiples Claves API por Endpoint - Asignar múltiples claves
• Autenticación - Entender autenticación de clave API
• Control de Acceso - Permisos y seguridad
• Manejo de Errores - Manejar errores de API
• Limitación de Velocidad - Limitaciones actuales

Ejemplos

Descargar Conjunto de Datos como SQL

curl "https://yourserver/api/org/proj/model/1/dataset/42?api_key=abc123xyz-def456uvw-ghi789rst&format=sql"

Descargar Conjunto de Datos como JSON Zip

curl "https://yourserver/api/org/proj/model/1/dataset/42?api_key=abc123xyz-def456uvw-ghi789rst&format=json-zip" \
  -o dataset.zip

Activar Pipeline

curl -X POST "https://yourserver/api/org/proj/model/1/pipeline/5?api_key=abc123xyz-def456uvw-ghi789rst"

Verificar Estado de Trabajo

curl "https://yourserver/api/job/507f1f77bcf86cd799439011"

Mejores Prácticas

1. Asegura tus claves - Nunca comprometas claves API al control de versiones
2. Usa HTTPS - Siempre usa conexiones encriptadas
3. Rota regularmente - Crea nuevas claves y elimina gradualmente las antiguas
4. Monitorea el uso - Verifica conteos de llamadas y tiempos de último uso
5. Usa propósitos descriptivos - Nombra claves por su caso de uso
6. Maneja errores - Implementa lógica de reintento para fallas transitorias