API

Asignación de Endpoints de API

Gigantics permite exponer conjuntos de datos y pipelines a través de endpoints REST API, habilitando acceso programático a sus recursos de datos sin requerir autenticación UI.

Cómo Funcionan los Endpoints

Cuando asigna un endpoint API a un conjunto de datos o pipeline, Gigantics crea una URL estable que puede ser accedida usando claves API. La URL del endpoint sigue este patrón:

https://yourserver/api/{organizacion}/{proyecto}/model/{secuenciaModelo}/{tipo}/{secuenciaRecurso}

Donde:

  • {organizacion} - El moniker de su organización
  • {proyecto} - El moniker de su proyecto
  • {secuenciaModelo} - El número de secuencia del modelo
  • {tipo} - Ya sea dataset o pipeline
  • {secuenciaRecurso} - El número de secuencia del conjunto de datos o pipeline

Asignando Claves API a Endpoints

Desde la Página de Conjuntos de Datos

  1. Navegue a Model → Datasets
  2. Haga clic en el ícono compartir (📤) en cualquier fila del dataset
  3. Si usted tiene solo una clave API en su proyecto, se asignará automáticamente
  4. Si tiene múltiples claves API, aparecerá un modal donde usted puede:
    • Buscar claves API por prefijo o propósito
    • Seleccionar una o más claves API para asignar
    • Hacer clic en "Assign" para agregar una clave, o "Assigned" para removerla
    • Hacer clic en "Confirm" para guardar la asignación

Desde la Página de Pipelines

  1. Navegue a Model → Pipelines
  2. Haga clic en el ícono compartir (📤) en cualquier fila del pipeline
  3. Siga el mismo proceso que para datasets

Creando Claves API

Antes de asignar endpoints, necesita crear claves API:

  1. Navegue a Project → API Keys (visible solo para usuarios con permiso ManageAPIKeys)
  2. Haga clic en "Create"
  3. Ingrese un propósito (e.g., "Production Access", "Development Testing")
  4. El sistema genera una clave en el formato: {prefijo}-{clave} (31 caracteres en total)
  5. Importante: Copie la clave inmediatamente - ¡solo se muestra una vez!

Tipos de Endpoints

Endpoints de Conjunto de Datos

Los endpoints de conjuntos de datos usan solicitudes GET y retornan los datos del conjunto en varios formatos.

Formato del endpoint:

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

Parámetros de consulta:

  • format - Formato de salida: sql, json, csv-zip, json-zip, o oracle-loader (por defecto: sql)
  • entity - Filtrar a una entidad/tabla específica por nombre
  • meta - Obtener metadata: entities (lista de nombres de entidad) o ddl (schema DDL)
  • archiveType - Para formatos zip: zip o tar (por defecto: zip)
  • limit - Limitar el número de registros retornados

Autenticación:

  • Incluir la clave API através del parámetro de consulta: ?api_key={su-clave}
  • O através del header: Authorization: Bearer {su-clave}

Endpoints de Pipelines

Los endpoints de pipelines usan solicitudes POST para disparar la ejecución del pipeline.

Formato del endpoint:

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

Respuesta:

{
  "job_id": "507f1f77bcf86cd799439011",
  "job_url": "https://yourserver/api/job/507f1f77bcf86cd799439011"
}

Autenticación:

  • Incluir la clave API através del parámetro de consulta: ?api_key={su-clave}
  • O através del header: Authorization: Bearer {su-clave}

Administrando Endpoints

Visualizando Endpoints Asignados

  • Desde la página de Claves API: Expanda cualquier fila de clave API para ver todos los endpoints que usan esa clave
  • Desde la página de Conjuntos de Datos/Pipelines: Expanda la fila del recurso para ver sus endpoints asignados

Cada endpoint muestra:

  • Método HTTP (GET para conjuntos de datos, POST para pipelines)
  • URI path completo
  • Número de llamadas realizadas a ese endpoint
  • Botón eliminar para remover el endpoint

Múltiples Claves API por Endpoint

Un endpoint único puede tener múltiples claves API asignadas. Esto habilita:

  • Rotación de claves sin downtime
  • Control de acceso multi-partes
  • Claves de respaldo para acceso de emergencia

Cuando se autentica, cualquiera de las claves asignadas funcionará. Ver Múltiples Claves API por Endpoint para detalles.

Eliminando Endpoints

  1. Navegue a la página de Claves API
  2. Expanda la fila de la clave API
  3. Haga clic en el ícono eliminar (🗑️) junto al endpoint
  4. Confirme la eliminación

Nota: Eliminar un endpoint remueve el acceso API pero no elimina el conjunto de datos o pipeline mismo.

Ciclo de Vida del Endpoint

Creación Automática de Endpoints

Cuando asigna claves API a un conjunto de datos o pipeline por primera vez, Gigantics automáticamente:

  1. Crea la URI del endpoint basada en la ubicación del recurso
  2. Asigna las claves API seleccionadas
  3. Establece el método HTTP apropiado (GET para conjuntos de datos, POST para pipelines)

Actualizaciones del Endpoint

  • La URI del endpoint permanece estable incluso si reasigna diferentes claves API
  • Agregar o remover claves API no cambia la URL del endpoint
  • El contador de calls del endpoint se incrementa con cada solicitud exitosa

Rotación de Claves

Para rotar claves API sin interrupción del servicio:

  1. Cree una nueva clave API
  2. Asigne tanto la clave vieja como la nueva al endpoint
  3. Actualice sus clientes para usar la nueva clave
  4. Monitoree el uso para confirmar la migración
  5. Remueva la clave vieja una vez que todos los clientes se hayan migrado

Mejores Prácticas

  1. Use propósitos descriptivos cuando cree claves API para rastrear su uso
  2. Copie las claves inmediatamente - solo se muestran una vez durante la creación
  3. Mantenga las claves seguras - trátelas como contraseñas
  4. Rote las claves regularmente - especialmente si una clave podría estar comprometida
  5. Monitoree el uso - revise los conteos de llamadas en los endpoints para rastrear patrones de acceso
  6. Use múltiples claves para diferentes ambientes o clientes para habilitar revocación granular

Documentación Relacionada

CSV

Página anterior

Managing API Keys

Página siguiente

Tabla de Contenidos