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 User Configuration. This will display the list of available users in the instance and their enabled permissions.

Server-side User

Userconfig API provides the "resource" information ("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.

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:

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.

URL Parameters and Description

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

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.

List of endpoints for the /userconfig:

• GET/userconfig/user
• GET/userconfig/export
• GET/userconfig/import
• PATH/user/instance{username}
• DELETE/user/instance{userName}

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": []
  }
  ]
  }

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.

• Base URL:

  http://<InstanceAddress>/rest/v1/userconfig/user/instance?userName=<name>

• Server Response if an invalid user name has been submitted:

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

• Server Response when deletion is successful:

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