External API

Edition: SaaS Enterprise

Agile Data Engine External API provides an interface for connecting external services with ADE processes. External API is exclusive for the SaaS Enterprise edition. A Swagger UI is provided which serves as a detailed documentation and enables manual API calls from a user interface mainly for development and testing purposes.

See also:

Using Metadata Interface

Usage

API URLs are in the following format:

https://external.services.saas.agiledataengine.com/external-api/api/{tenant}/{installation}/{environment}/...

Where:

{tenant} is the SaaS tenant, e.g. s1234567.
{installation} = datahub
{environment} is the environment name, e.g. design, dev, test or prod.

Tenant name is part of the URL of your Agile Data Engine account. Environment names are listed in the Designer front page under Environments.

Access the Swagger UI here. Select the interface with Select a definition.

CLI tool

A command line interface (CLI) tool for using External API is available in Github.

Authentication

All requests have to be authenticated. When calling the APIs from an external service, authentication is done with an API key and secret which are provided by the Agile Data Engine support team. Also, the public IP address of the service executing the requests has to be allowed by the support team. Allowed IP addresses are configured per API key.

Authentication in the user interface:

Navigate to the Swagger UI.
Select the interface from the top with Select a definition.
Input Tenant, Installation and Environment.
Authorize the requests by pressing Authorize, input your API key and key secret.

Interfaces

Currently External API supports the following features:

Interface	Environment Type	Description
Dagger	RUNTIME	Trigger workflows (DAGs) and query workflow run status.
Deployment	DESIGN	Query the commits, promotion and deployment statuses of package versions per environment. Export package JSON of a certain commit. Control promotions, demotions and deploys.
Run ID	RUNTIME	Query, Add, Remove Run IDs per environment and entity.
Code	RUNTIME	Get generated runtime load steps of a certain package / a certain entity.
Metadata	DESIGN, RUNTIME	Query ADE metadata using GraphQL.

Please refer to the Swagger UI for detailed instructions.

Examples

Python function for triggering a DAG

This basic Python function can be used for triggering a DAG using the Dagger v2 API:

PY

import os
import requests
import json

"""
    Base URL and API keys from environment variables in this example.
    API keys are environment-specific.

    Base URL format:
    https://external.services.saas.agiledataengine.com/external-api/api/{tenant}/{installation}/{environment}
    e.g. https://external.services.saas.agiledataengine.com/external-api/api/s1234567/datahub/dev
"""

def trigger_dag(dag_id: str):
    """
    Trigger a DAG run via the external API.
    
    Args:
        dag_id (str): The name of the DAG to trigger.
    
    Returns:
        dict: The parsed JSON response from the API if successful.
    
    Raises:
        ValueError: If required environment variables are missing.
        requests.RequestException: If the HTTP request fails.
        json.JSONDecodeError: If the response is not valid JSON.
    """
    base_url = os.getenv('BASE_URL')
    api_key = os.getenv('API_KEY')
    api_key_secret = os.getenv('API_KEY_SECRET')

    if not base_url or not api_key or not api_key_secret:
        raise ValueError("Missing required environment variables: BASE_URL, API_KEY, or API_KEY_SECRET")

    url = f"{base_url}/dagger/v2/dags/{dag_id}/dag-runs"

    with requests.Session() as session:
        session.headers.update({
            "X-API-KEY-ID": api_key,
            "X-API-KEY-SECRET": api_key_secret,
            "Content-Type": "application/json"
        })

        response = session.post(url)

        # Raise HTTPError for bad responses (4xx and 5xx)
        response.raise_for_status()

        try:
            return response.json()
        except json.JSONDecodeError as e:
            raise json.JSONDecodeError(f"Failed to decode JSON response: {response.text}") from e