API v1 - Userconfig

The Userconfig endpoints allow you to get the list of internal users and user data available within the Matillion ETL instance. Users are administered through the User Configuration dialog within the Matillion ETL client interface.

The Userconfig API provides the "resource" information ("resources" refers to the information returned by an API). These resources usually have various endpoints that are combined with multiple HTTP methods (GET, POST) for each endpoint. The Userconfig API family has one PATH method that allows you to get the selected user information available in the 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 calls.
The Userconfig API will only be available for admin users of Matillion ETL.

Using the API

Access the Userconfig API by making GET, POST, or DELETE calls with the form:

<instanceAddress>/rest/v1/userconfig/<endpoint>

Where:

<instanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
<endpoint> is the name of the API endpoint that accomplishes the task you want to perform. These endpoints are documented in the following sections.

GET userconfig/user

To retrieve the list of users associated with the Matillion ETL instance, make the following GET call:

<instanceAddress>/rest/v1/userconfig/user

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

[
    {
    "name": "api-user",
    "admin": true,
    "api": true,
    "projectAdmin": false,
    "currentLoggedInUser": false
  },
  {
    "name": "TestUser1",
    "admin": true,
    "api": true,
    "projectAdmin": true,
    "currentLoggedInUser": false
  },
]

GET userconfig/export

To export the user configuration from the Matillion ETL instance, make the following GET call:

<instanceAddress>/rest/v1/userconfig/export

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

{
    "objects": [
        {
            "type": "Internal",
            "users": [
               {
                    "username": "TestUser",
                    "password": "ee26b0dd4af7e749aa1a8ee3c10ae99",
                    "isServerAdmin": true,
                    "isApi": true,
                    "isProjectAdmin": true
                },
                {
                    "username": "TestUser1",
                    "password": "c7ad44cbad762a5da0a452f9e854fdc",
                    "isServerAdmin": true,
                    "isApi": true,
                    "isProjectAdmin": false
                },
                    ]
        }
    ],
    "version": "1.44.11",
    "environment": "redshift"
}

POST userconfig/import

Used to import a user configuration (exported with GET userconfig/export) to a Matillion ETL instance. When importing, there is no "merge" option. If a resource of the same name already exists, you must delete the existing resource before importing the new one.

Make the following POST method API call:

<instanceAddress>/rest/v1/userconfig/import

This will be a POST method API call as we will have to include the user configuration in the body as a JSON file with the following format. This is the JSON format produced by the output of the userconfig/export method.

{
    "objects": [
        {
            "type": "Internal",
            "users": [
                {
                    "username": "TestUser-Imported",
                    "password": "ee26b0dd4af7e749aa1a8ee3c10ae99",
                    "isServerAdmin": true,
                    "isApi": true,
                    "isProjectAdmin": true
                },
                {
                    "username": "TestUser1-Imported",
                    "password": "c7ad44cbad762a5da0a452f9e854fdc",
                    "isServerAdmin": true,
                    "isApi": true,
                    "isProjectAdmin": false
                },
                    ]
        }
    ],
    "version": "1.44.11",
    "environment": "redshift"
}

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

{
  "name": "User Configuration",
  "statusList": [
    {
      "success": true,
      "name": "Internal"
    }
  ],
  "success": true
}

PATH user/instance?userName

Whenever you reach a named resource endpoint, the API will expose API metadata for that resource, including PATH, GET, POST, and DELETE method options available. In the example below, the metadata would show PATH options for the specified username.

<instanceAddress>/rest/v1/userconfig/user/instance?userName=<username>

This will return the following response from the server, in JSON format:

{
  "endpoints": [
    {
      "httpMethod": "PATH",
      "name": "UserInstanceService",
      "children": [
        ],
      "type": "UserInstanceService"
    }
  ],
  "dataTypes": [
    {
      "type": "RestResponse",
      "fields": []
    }
  ]
}

DELETE user/instance?userName

This is a DELETE request API call, which will delete a single user with the user name specified in the URL parameter.

<instanceAddress>/rest/v1/userconfig/user/instance?userName=<username>

This will return the following response from the server, in JSON format, if an invalid user name has been submitted:

{
    "success": false,
    "msg": "Unable to find user with name [fake-user].",
    "id": -1
}

When deletion is successful, the following response is returned from the server:

{
    "success": true,
    "msg": "Successfully deleted user [my-user].",
    "id": 0
}