API v1 - Environment

API v1 - Environment


This is a guide to providing details on the Environment API from the familiy of the Group API. The Environment endpoint allows users to explore and manages the "Environment" and "Variables" available within the Matillion ETL instance. An Environment in Matillion describes a single connection to a database, on which Matillion ETL jobs can be run.

Environments can be set up at user-level via Project Menu Add Environment within the instance.

The Environemnt API benefits to explore and manages the Environment Variables using PATH/variable endpoints. Environment variables are "name:value" pairs that are stored inside the Matillion ETL client and fully configurable by its users. Unlike Job Variables, Environment Variables can be used throughout the client, in configurations and in all jobs through many components. Environment variables must be declared before being used. You set a variable by selecting Project Menu Manage Environment Variables

Manage Environment Variable

Manage Environment Variable

The Environment API provides the "resource" details available within the Project in the Matillion ETL instance. By "resources" here, we refer to explore and analyse the details of the Matillion Environment and Environment Variables, within the specific Project. Environment API endpoint (PATH/Environment) is a part of PATH/project which is further combined with HTTP methods (GET, POST, and DELETE) for unique combinations to get the "resource" information for the Matillion ETL instance. Whereas, PATH/variable is a part of PATH/environment API, please refer to Graphical Representation section of this guide.

Important Information

  • This document is part of a series on API v1 - Group and the Matillion ETL API - v1.
  • Users responsible for experimenting with Matillion ETL API services require access to the Matillion ETL instance and ought to know how to make REST API calls either employing a REST API GUI client such as Postman or employing a command-line interface like cURL.
  • Matillion ETL API endpoints require authorisation to make any REST API call, so ensure a username and password for the Matillion ETL instance is configured before making any API call.

Environment API Endpoints

API Base URL

http(s)://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/environment

API Endpoints and Function

Environment endpoint API is available on standard REST-based APIs that uses HTTP or HTTPS request to GET, POST, and DELETE data. These API service is accessed through the Uniform Resource Identifier (URI). The available API endpoints are listed below:

Method Path URI Function
GET /name http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/name Get the name of the current environment.
GET /id http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/id Get the id of the selected environment.
GET /test http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/test Test the current environment.
GET /export http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/export To export the data of the current environment within the project.
POST /update http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/update WITH POST DATA arg0 Update the current environment by importing updated environment.
PATH/variable
GET /value http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/value Returns default value for current environment variable.
POST /delete http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/delete Delete the current variable.
POST /set/value/{variableValue} http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/set/value/<variableValue> Set new value for current Environment Variable.
POST /set/instance http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/set/instance?variableValue=<variableValue> Set new value for current Environment Variable
DELETE /variableName http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName> Delete the current variable using DELETE HTTP method.

Graphical Represenation

To illustrate the Environment API v1, endpoints and methods to the further, below is the graphical flow of the /environment endpoint showing possible PATH, GET , POST, and DELETE options.

Environment endpoint Flow

Environment endpoint Flow



URL Parameters and Description

Below is the list of endpoint parameters and their brief description:

Parameters Name Description
<InstanceAddress> This is the server IP address or domain name.
<groupName> the name of the group.
<projectName> The name of the project within the group.
<environmentName> The name of the environment within the selected project.
<variableName> The name of the variable within the selected environment.
<name> To get the name of the resource.
<export> This allows to export the metadata of the selected resource.
<delete> Delete the selected resource.
<id> The queue id of the current resource.
<test> To test the seleted environment.
<value> The value for current environment variable.



Endpoints and Server Response

This chapter describes the Environment API endpoints with examples. These APIs offers REST-based web service, offering ease of use and a flexible choice of programming language. These APIs can be used to access and analyse the "Environment" and "Environment Variables" within the Project in the instance.

The goal here is to provide a bitesized, independent, generic example of the GET, POST and DELETE options found in the Environment API endpoints and Environment Variable API endpoints.

PATH/environment

List of endpoints for the /environment:

Below is the detailed description of these endpoints with example response from the server.

GET/name

This example is a GET method REST API request that will provide the name of the environment within the project in the instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/name
  • Server Response
    API Environment

GET/id

This is to get the id for the selected version within the project using GET HTTP method.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/id
  • Server Response
    796

GET/test

This is to test the selected environment within the project using GET HTTP method.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/test
  • Server Response
    {
      "success": true,
      "msg": "Testing environment [API Environment] was successful.",
      "id": 0
    }

GET/export

To export the selected environment detail from the project within the Matillion instance, provide the environmentName and use the /export endpoint. This example using GET method REST API call to export the environment details available within the selected project.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/export
  • Server Response
    {
        "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

To update the current environment by importing updated environment within the Matillion instance, use the /update endpoint. This example using GET method REST API call to export the environment details available within the selected project.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/update WITH POST DATA arg0
  • POST Body
    		{
        "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"
    }
  • Server Response
    {
      "name": "Environments",
      "statusList": [
        {
          "success": true,
          "name": "test"
        }
      ],
      "success": true
    }

  • PATH/variable

    The PATH/variable is a part of the PATH/environment, which is further combined with HTTP methods GET, POST and DELETE for unique combinations to get the Variable information within the Environment. Variables are "name-value" pairs stored within each Environment. Variables can be used in all sorts of parameters and expressions to allow the user to pass and centralise environment specific configuration

    List of endpoints associated with the /variable.

    Below is the detailed description of these endpoints with example response from the server.

    GET/value

    This example is a GET method REST API request that will returns default value for current environment within the project in the instance.

    • Base URL
      http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/value
    • Server Response
      date

    POST/delete

    This will be a POST method API call. The /delete endpoint will allow to delete the selected environment within the instance.

    • Base URL
      http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/delete
    • Server Response
      {
        "success": true,
        "msg": "Successfully removed variable [test_API] from environment [API Environment].",
        "id": 0
      }

    POST/set/value/{variableValue}

    The endpoint will allow to set new value for current Environment Variable within the instance. This is a POST method API call as need to provide the <variableValue> in the "URL" to set into the current Environment.

    • Base URL
      http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/set/value/<variableValue>
    • Server Response
      {
        "success": true,
        "msg": "Successfully set value [2] for variable [test_API].",
        "id": 0
      }

    POST/set/instance

    The endpoint will allow to set new value for current Environment Variable within the instance. This is a POST method API call as need to provide the <variableValue> in the "URL" to set into the current Environment.

    • Base URL
      http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>/set/instance?variableValue=<variableValue>
    • Server Response
      {
        "success": true,
        "msg": "Successfully set value [4] for variable [test_API].",
        "id": 0
      }

    DELETE/variableName

    To remove any resource from the list, we will use DELETE API request. In this example, we will delete a variable from the Environment.

    • Base URL
      http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/environment/name/<environmentName>/variable/name/<variableName>
    • Server Response
      {
        "success": true,
        "msg": "Successfully removed variable [test_api] from environment [API Environment].",
        "id": 0
      }