API v1 - Userconfig

API v1 - Userconfig


Overview

This is a guide to providing details on the Userconfig API services offered by Matillion ETL. These services provide the list of internal users created and data available within the Matillion ETL instance. The 'Internal' option uses an internal (instance-side) database of username, passwords and privileges. You can add, remove and modify users in the Security Configuration section.

Users can be found in the Admin tab at the top-right of your Matillion ETL window and select the User Configuration. This will display the list of available users in the instance and their enabled permissions.

Server-side Users

Server-side User

Userconfig API provides the "resource" informaton (“Resources” refers to the information returned by an API). These resources usually have various endpoints which are combined with multiple HTTP methods (GET, POST) for each endpoint. Userconfig API family has one PATH that allows to get the selected user information available in the instance.

Important Information and Links

Please take note of the following information before getting started:

  • 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.
  • For more information about accessing the Matillion API, and general information on the Matillion API platform before using the Userconfig API, please refer to Matillion ETL API Introduction.
  • 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.

Userconfig API Endpoints

API Base URL

http(s)://<InstanceAddress>/rest/v1/<userconfig>

API Endpoints and Function

Userconfig API is available on standard REST-based APIs that uses HTTP or HTTPS request to GET and POST data. The Userconfig API service is accessed through the Uniform Resource Identifier (URI). All following references in this document will assume the API Base URL has been specified. The available API endpoints are listed below:

Method Path URI Function
GET userconfig/user http://<InstanceAddress>/rest/v1/userconfig/user Retrieve a list of all users.
GET userconfig/export http://<InstanceAddress>/rest/v1/userconfig/export To export user configuration.
POST userconfig/import http://<InstanceAddress>/rest/v1/userconfig/import WITH POST DATA arg0 To import user configuration.
PATH user/instance{username} http://<InstanceAddress>/rest/v1/userconfig/user/instance?userName=<username> Get a user configuration by name

Graphical Representation

To illustrate the Userconfig API, endpoints and methods to the further, below is the graphical flow of the /userconfig endpoint showing possible PATH, GET and POSToptions.

Userconfig endpoint Flow

Userconfig 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.
<userconfig> The user configuration within the Matillion ETL instance.
<export> This property export the user configuration available in the instance.
<import> This allows to import the user configuration and details available within the instance.
<userconfig/user> This property allows to retieve the user configuration using the selected name.

Endpoints and Server Response

This chapter describes the Userconfig APIs endpoints and 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 users data, export and import within the Matillion ETL instance.

All the APIs listed in this chapter are available to use with GET, POST, and a PATH methods to retrieve the list of users, import or export the user data available within the instance.

List of endpoints for the /userconfig:

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

GET/userconfig/user

In the example below, we will be retrieving a single resource information, perform a GET request for that named resource endpoint. The endpoint will retrieve the list of users associated with the instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/userconfig/user
  • Server Response
    [
    	{
        "name": "api-user",
        "admin": true,
        "api": true,
        "projectAdmin": false,
        "currentLoggedInUser": false
      },
      {
        "name": "TestUser1",
        "admin": true,
        "api": true,
        "projectAdmin": true,
        "currentLoggedInUser": false
      },
    ]


GET/userconfig/export

This is a Get request API call, which will export the user configuration available within the Matillion ETL instance by adding /export endpoint in the base URI.

  • Base URL
    http://<InstanceAddress>/rest/v1/userconfig/export
  • Server Response
    {
        "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

Now that you have an exported user configuration (see previous example), this time we use the API to import that user configuration into a Matillion ETL instance. Note that, 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.This will be a POST method API call as we will have to attach the project (in JSON form, as exported), in the body as a JSON file to import into the Matillion ETL instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/userconfig/import
  • POST Body (JSON)
    {
        "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"
    }
  • Server Response
    {
      "name": "User Configuration",
      "statusList": [
        {
          "success": true,
          "name": "Internal"
        }
      ],
      "success": true
    }


PATH/user/instance{username}

In the example below, we will be retrieving a single resource information, perform a GET request for that named resource endpoint.

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

  • Base URL
    http://<InstanceAddress>/rest/v1/userconfig/user/instance?userName=<username>
  • Server Response
    {
      "endpoints": [
        {
          "httpMethod": "PATH",
          "name": "UserInstanceService",
          "children": [
            ],
          "type": "UserInstanceService"
        }
      ],
      "dataTypes": [
        {
          "type": "RestResponse",
          "fields": []
        }
      ]
    }