API Endpoint Assignment

Gigantics allows you to expose datasets and pipelines through REST API endpoints, enabling programmatic access to your data resources without requiring UI authentication.

How Endpoints Work

When you assign an API endpoint to a dataset or pipeline, Gigantics creates a stable URL that can be accessed using API keys. The endpoint URL follows this pattern:

https://yourserver/api/{organization}/{project}/model/{modelSequence}/{type}/{resourceSequence}

Where:

• {organization} - Your organization's moniker
• {project} - Your project's moniker
• {modelSequence} - The model sequence number
• {type} - Either dataset or pipeline
• {resourceSequence} - The dataset or pipeline sequence number

Assigning API Keys to Endpoints

From the Datasets Page

1. Navigate to Model → Datasets
2. Click the share icon (📤) on any dataset row
3. If you have only one API key in your project, it will be automatically assigned
4. If you have multiple API keys, a modal will appear where you can:
   • Search for API keys by prefix or purpose
   • Select one or more API keys to assign
   • Click "Assign" to add a key, or "Assigned" to remove it
   • Click "Confirm" to save the assignment

From the Pipelines Page

1. Navigate to Model → Pipelines
2. Click the share icon (📤) on any pipeline row
3. Follow the same process as for datasets

Creating API Keys

Before assigning endpoints, you need to create API keys:

1. Navigate to Project → API Keys (visible only to users with ManageAPIKeys permission)
2. Click "Create"
3. Enter a purpose (e.g., "Production Access", "Development Testing")
4. The system generates a key in the format: {prefix}-{key} (31 characters total)
5. Important: Copy the key immediately - it's only shown once!

Endpoint Types

Dataset Endpoints

Dataset endpoints use GET requests and return the dataset data in various formats.

Endpoint format:

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

Query parameters:

• format - Output format: sql, json, csv-zip, json-zip, or oracle-loader (default: sql)
• entity - Filter to a specific entity/table name
• meta - Get metadata: entities (list of entity names) or ddl (schema DDL)
• archiveType - For zip formats: zip or tar (default: zip)
• limit - Limit the number of records returned

Authentication:

• Include API key via query parameter: ?api_key={your-key}
• Or via header: Authorization: Bearer {your-key}

Pipeline Endpoints

Pipeline endpoints use POST requests to trigger pipeline execution.

Endpoint format:

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

Response:

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

Authentication:

• Include API key via query parameter: ?api_key={your-key}
• Or via header: Authorization: Bearer {your-key}

Managing Endpoints

Viewing Assigned Endpoints

• From API Keys page: Expand any API key row to see all endpoints using that key
• From Datasets/Pipelines page: Expand the resource row to see its assigned endpoints

Each endpoint shows:

• HTTP method (GET for datasets, POST for pipelines)
• Full URI path
• Number of calls made to that endpoint
• Delete button to remove the endpoint

Multiple API Keys per Endpoint

A single endpoint can have multiple API keys assigned. This enables:

• Zero-downtime key rotation
• Multi-party access control
• Backup keys for emergency access

When authenticating, any of the assigned keys will work. See Multiple API Keys per Endpoint for details.

Deleting Endpoints

1. Navigate to the API Keys page
2. Expand the API key row
3. Click the delete icon (🗑️) next to the endpoint
4. Confirm deletion

Note: Deleting an endpoint removes API access but does not delete the dataset or pipeline itself.

Endpoint Lifecycle

Automatic Endpoint Creation

When you assign API keys to a dataset or pipeline for the first time, Gigantics automatically:

1. Creates the endpoint URI based on the resource location
2. Assigns the selected API keys
3. Sets the appropriate HTTP method (GET for datasets, POST for pipelines)

Endpoint Updates

• The endpoint URI remains stable even if you reassign different API keys
• Adding or removing API keys doesn't change the endpoint URL
• The endpoint calls counter increments with each successful request

Key Rotation

To rotate API keys without service interruption:

1. Create a new API key
2. Assign both the old and new keys to the endpoint
3. Update your clients to use the new key
4. Monitor usage to confirm migration
5. Remove the old key once all clients have migrated

Best Practices

1. Use descriptive purposes when creating API keys to track their usage
2. Copy keys immediately - they're only shown once during creation
3. Keep keys secure - treat them like passwords
4. Rotate keys regularly - especially if a key might be compromised
5. Monitor usage - check the call counts on endpoints to track access patterns
6. Use multiple keys for different environments or clients to enable granular revocation

Related Documentation

• Multiple API Keys per Endpoint - Learn about assigning multiple keys
• Authentication - Understand how API authentication works
• Access Control - Review permissions required for API management