Skip to content

API v1 - Environment

The Environment API endpoint can be used to explore and manage environments in your Matillion ETL instance, using PATH environment endpoints, and to explore and manage environment variables using PATH variable endpoints.

An environment describes a single Matillion ETL connection to a database on which Matillion ETL jobs are run.

Environment variables are name:value pairs that are stored inside the Matillion ETL client and fully configurable by its users. Environment variables can be used throughout a project, in many components in any of the project's jobs.

Note

Environment variables must be declared before being used.

The environment endpoint /environment is a part of /project, and the variable endpoint /variable is a part of /environment. These endpoints provide unique paths to specific environments and environment variables within a project. Used with the HTTP methods GET, POST, and DELETE, this allows you to retrieve and manipulate any environment and environment variable details from your Matillion ETL instance.

Prerequisites

  • To use Matillion ETL API services, you must know how to make REST API calls, either by employing a REST API GUI client such as Postman, or employing a command line interface (CLI) like cURL.
  • If you are new to Matillion ETL's API, read our Matillion API introduction and explore the v1 API map.
  • Matillion ETL API endpoints require authorization to make any REST API call, so ensure a username and password for the Matillion ETL instance is configured before making any API call.

Using the API

There are two base URLs for the Environment API:

  • Environment endpoints: <InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/
  • Variable endpoints: <InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/variable/

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.

GET name

Returns the name of the project's environment in this Matillion ETL instance.

To return the name of the environment, make the following GET call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/name

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.

A successful GET call to the endpoint will return the following response from the server, in JSON format:

{
  API Environment
}

GET id

Returns the project environment's ID in this Matillion ETL instance.

To return the environment's ID, make the following GET call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/id

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.

A successful GET call to the endpoint will return the following response from the server, in JSON format:

{
    796
}

GET test

Tests the selected environment in the project of this Matillion ETL instance.

To test the project's environment, make the following GET call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/test

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.

A successful GET call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Testing environment [API Environment] was successful.",
    "id": 0
}

GET export

Exports details of the selected environment configuration, in JSON format.

To export the environment, make the following GET call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/export

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.

A successful GET call to the endpoint will return the following response from the server, in JSON format:

{
    "objects": [
        {
            "name": "API Environment",
            "credentialsName": "Instance Credentials",
            "gcCredentialsName": "GCP",
            "azureCredentialsName": "aws_azure",
            "schema": "public",
            "encrypted": false,
            "url": "mtln-rs-006.ck4qmenbus4m.eu-west-1.redshift.amazonaws.com",
            "port": "5432",
            "database": "admin",
            "driver": null,
            "user": "admin",
            "passwordName": "API PROJECT-test",
            "passphraseName": null,
            "role": "",
            "variables": {},
            "defaultStorageLocation": "cf-templates-bvdzucx2zo3e-us-east-1",
            "concurrentConnections": 1,
            "passwordType": "PASSWORD",
            "connectionOptions": {}
        }
    ],
    "version": "master",
    "environment": "redshift"
}

POST update

Updates details of the selected environment.

A typical use of this would be to clone an existing environment by using GET export to retrieve its details, and then passing those details into an existing environment using POST update.

To update details of the selected environment, make the following POST call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/update WITH POST DATA arg0

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.

The POST body should contain the following, in JSON format:

{
    "objects": [
        {
            "name": "test",
            "credentialsName": "Instance Credentials",
            "gcCredentialsName": "GCP",
            "azureCredentialsName": "aws_azure",
            "schema": "public",
            "encrypted": false,
            "url": "mtln-rs-006.ck4qmenbus4m.eu-west-1.redshift.amazonaws.com",
            "port": "5432",
            "database": "admin",
            "driver": null,
            "user": "admin",
            "passwordName": "API PROJECT-test",
            "passphraseName": null,
            "role": "",
            "variables": {},
            "defaultStorageLocation": "cf-templates-bvdzucx2zo3e-us-east-1",
            "concurrentConnections": 1,
            "passwordType": "PASSWORD",
            "connectionOptions": {}
        }
    ],
    "version": "master",
    "environment": "redshift"
}

Note

This format is the same as the server response of a GET export request.

A successful POST call to the endpoint will return the following response from the server, in JSON format:

{
    "name": "Environments",
    "statusList": [
    {
        "success": true,
        "name": "test"
    }
    ],
    "success": true
}

POST import

Imports details of the selected environment.

A typical use of this would be to clone an existing environment by using GET export to retrieve its details, and then passing those details into a new environment using POST import.

To import the environment details, make the following POST call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/import

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.

The POST body should contain the exported environment, and look similar to the following, in JSON format:

{
    "objects": [
      {
        "name": "your-environment-name",
        "credentialsName": "Instance Credentials",
        "gcCredentialsName": "",
        "azureCredentialsName": "",
        "catalog": "",
        "schema": "PUBLIC",
        "encrypted": false,
        "url": "your-database-url",
        "port": "your-cloud-warehouse",
        "database": "your-database-name",
        "driver": null,
        "user": "username",
        "passwordName": "userpassword",
        "passphraseName": null,
        "role": "PUBLIC",
        "variables": {},
        "defaultStorageLocation": "",
        "concurrentConnections": 1,
        "passwordType": "PASSWORD",
        "connectionOptions": {},
        "defaultEnvironment": true
      }
    ],
    "version": "Built",
    "environment": "snowflake"
}

A successful POST call to the endpoint will return the following response from the server, in JSON format:

{
    "name": "Environments",
    "statusList": [
        {
            "success": true,
            "name": "your-environment-name"
        }
    ],
    "success": true
}

GET value

Returns the default value of a specified environment variable.

To return the default value of the environment variable, make the following GET call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/value

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.
  • <variableName> is the variable in the selected environment.

A successful GET call to the endpoint will return the following response from the server, in JSON format:

{
    date
}

POST delete

Delete the default value of an environment variable in the specified environment. See also DELETE name.

To delete default value of an environment variable in the specified environment, make the following POST call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/delete

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.
  • <variableName> is the variable in the selected environment.

A successful POST call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully removed variable [test_API] from environment [API Environment].",
    "id": 0
}

POST set value

Set a new value for a specified environment variable. The value must be provided as <variableValue> in the URL, as shown below.

Note

The POST set instance endpoint calls the exact same code as Post set value. Post set instance is an alias of Post set value. If you want to use POST set instance, make the following POST call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/set/instance?variableValue=<variableValue>

To set a new value for a specified environment variable, make the following POST call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/set/value/<variableValue>

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.
  • <variableName> is the variable in the selected environment.
  • <variableValue> is the new value for the variable.

A successful POST call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully set value [2] for variable [test_API].",
    "id": 0
}

DELETE name (in environment)

Delete the default value for a variable in the specified environment. See also POST delete.

To delete the default value for a variable in the specified environment, make the following DELETE call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.
  • <variableName> is the variable in the selected environment.

A successful DELETE call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully removed variable [test_api] from environment [API Environment].",
    "id": 0
}

DELETE name (in project)

Delete the specified variable from the project.

To delete the project variable, make the following DELETE call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/variable/name/<variableName>

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <variableName> is the variable in the selected environment.

A successful DELETE call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully removed variable [test_api] from project [API Project].",
    "id": 0
}

GET variable export

Exports all environment variables in the selected environment, as name:value pairs in JSON format.

To export all environment variables in the selected environment, make the following GET call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/variable/export

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.

A successful GET call to the endpoint will return the following response from the server, in JSON format:

{
    "objects": [
        {
            "name": "Example_variable",
            "value": "88.8"
        },
    ],
    "version": "master",
    "environment": "redshift"
}

POST variable import

Imports environment variables into the specified environment.

To import environment variables into the specified environment, make the following POST call:

<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment/name/<environmentName>/variable/import

Where:

  • <InstanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <groupName> is the name of the project group.
  • <projectName> is the name of the project in the group.
  • <environmentName> is the name of the environment in the selected project.

The POST body should contain the following, in JSON format:

{
    "objects": [
        {
            "name": "Example_Variable",
            "value": "22.1"
        }
    ],
    "version": "master",
    "environment": "redshift"
}

Note

This format is the same as the server response of a GET variable export request.

A successful POST call to the endpoint will return the following response from the server, in JSON format:

{
    "name": "Environment Variables",
    "statusList": [
        {
            "success": true,
            "name": "Example_Variable"
        }
    ],
    "success": true
}

Note

To import and export variables at the project level, use the Group/Project API.