API v1 - Permission

API v1 - Permission


Overview

This is a guide to providing details on the Permission API services offered by Matillion ETL. The Permission API gives details on set of permissions that either allow or restrict access to each group of Matillion ETL.

The Permissions in Matillion ETL allow admins to specify what parts of the client each user has access to or restrictiuon if any. To enable Permissions on the server, an Admin must ensure that the Security Configuration Admin User Configuration is set to "Internal" or "External". That will allow admin to "Manage Groups" and "Manage Permissions" through Admin menu. View Permissions is available through the Help menu and can be managed by both "Admins" and regular users.

Manage Permissions

Manage Permissions

Permission API provides the "resource" data (“Resources” refers to the information returned by an API). These resources usually have various endpoints which are combined with multiple HTTP methods for each endpoint. Permissions API family consist of some PATHs that combined with number of endpoint resources using HTTP methods GET, POST, and DELETE.

Important Information

  • This document is part of a series on the Matillion ETL API - v1.
  • This process requires the Matillion ETL instance URL, the username and password of a user with appropriate permissions.
  • 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.

Permission API Endpoints

API Base URL

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

API Endpoints and Function

Permission API is available on standard REST-based APIs that uses HTTP or HTTPS request to GET and POST data. The Permission 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
PATH/user
PATH /user http://<InstanceAddress>/rest/v1/permission/user Get the list of users.
PATH/group
GET /parent http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/parent Get the parent Group ID of the selected permission group.
GET /export http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/export Export the selected permission group.
DELETE /groupName http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/ Delete the selected permission group via a HTTP DELETE request.
POST /update http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/update WITH POST DATA arg0 Update the selected permission group.
POST /delete http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/delete Delete the selected permission group via a HTTP POST request.
PATH/<groupName>/roles
GET /get http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/roles/get Get the list of roles assigned to the selected permission group.
POST /add http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/roles/get Add a role to the selected permission group.
POST /remove http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/roles/remove WITH POST DATA arg0 Remove a role from the selected permission group.
PATH/global
POST /import http://<InstanceAddress>/rest/v1/permission/global/import WITH POST DATA arg0 Import one or more group permissions.
GET /export http://<InstanceAddress>/rest/v1/permission/global/export Export all permissions for every group.
GET /group http://<InstanceAddress>/rest/v1/permission/global/group List all group permission.
PATH/instance
PATH /group http://<InstanceAddress>/rest/v1/permission/global/instance?groupName=<groupName> Get the permission of the selected instance using groupName.
PATH/group/name/<groupName>
GET /export http://<InstanceAddress>/rest/v1/permission/global/group/name/<groupName>/export Export all permissions for the selected group.
GET /permission http://<InstanceAddress>/rest/v1/permission/global/group/name/<groupName>/permission List permission in the selected group.
POST /clear http://<InstanceAddress>/rest/v1/permission/global/group/name/<groupName>/clear Reset permissions for the selected group.
PATH/permission/name/<permissionName>
GET /get http://<InstanceAddress>/rest/v1/permission/global/group/name/<groupName>/permission/name/<permissionName>/get Get the selected permission.
POST /update http://<InstanceAddress>/rest/v1/permission/global/group/name/<groupName>/permission/name/<permissionName>/update Update the selected permission. (DEFAULT, GRANTED, FORBIDDEN)

Graphical Represenation

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

Permission API Endpoint Flow

Permission API 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.
<permissionName> The name of the permission created in Matillion ETL.
<user> This allows to get the list of users.
<update> This allows to update the selected permissions.
<get> This property will get the permissions associated with the groups in the Matillion ETL instance.
<clear> Reset the permissions.
<roles> This defines the roles assigned to the permission.
<remove> This will remove the selected property from the instance..

Endpoints and Server Response

This chapter describes the Permission 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 notice and its id associated with the Matillion ETL instance.

Before we start working with any Permission endpoint call. It would be recommended to understand the concept of PATH used in Permission API family.

A PATH is a unit of a REST API that you can call. A PATH comprises an HTTP Method (GET/POST/DELETE) and a URL PATH that, when exposed, is combined with the base PATH URL (<server address>/rest/v1) of the API.

The Permission API family comprises of following PATHs:

The graphical view of the Permission API PATHs shown below:

Permission Endpoint PATH

Permission Endpoint PATH

Once, you have basic understanding of PATH and associated HTTP methods, you can start making API requests.
All the APIs listed in this chapter are available to use with GET/POST/DELETE methods to retrieve the "resource" information. The detailed description of each endpoint and associated methods is discussed in the next section of this guide.

PATH/user

This is a PATH for the user permissions within the Matillion ETL instance. This will provide the list of users assigned permissions for the instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/user
  • Server Response
    [
    	"user-1"
    	"user-2"
    	"user-3"]

PATH/group

PATH/group is a primary PATH for the API Base URL of Permission API alligned with two HTTP method (GET,POST,DELETE) and a PATH to make a unique operation for the resource to retieve the information correlated with the permissions associatd with the groups in the instance.

List of endpoints for the PATH/group:

GET/parent

This example is a GET method REST API request that will provide the parent Group ID of the selected permission group within the Matillion ETL instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/parent
  • Server Response
    123456

GET/export

To export the selected permission group within the Matillion instance, provide the groupName and use the /export endpoint. This example using GET method REST API call to export the selected permission group and all associated information alligned with the group.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/export
  • Server Response
    {
        "objects": [
            {
                "name": "Example-Group",
                "otherRoles": [],
                "parentGroupID": null
            }
        ],
        "version": "1.44.11",
        "environment": "redshift"
    }

DELETE/groupName

To remove any resource from the list, we will use DELETE API request. In this example, we will delete a permission group from within the permissions in the Matillion ETL instance.

Please Note

There are often multiple ways of achieving the same task within the API as resources and methods branch out and overlap.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>
  • Server Response
    {
      "success": true,
      "msg": "Successfully deleted schedule [Exampleschedule]",
      "id": -1
    }

POST/update

The /update endpoint will allow to update the selected permission group. 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/permission/group/name/<groupName>/update WITH POST DATA arg0
  • POST BODY(JSON)
    {
                "name": "Writer",
                "otherRoles": [],
                "parentGroupID": null
    }

    Below is the description of the fields included in the POST body:

    Field Name Description
    name The name of the permission group
    otherRoles The new role if required to be added. The type of the field should be "string".
    parentGroupID The id of the parent group, if available.
  • Server Response
    {
      "success": true,
      "msg": "Successfully updated the permission group: Writer",
      "id": -1
    }

POST/delete

This will be a POST method API call. The /delete endpoint will allow to delete the selected permission group.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/delete
  • Server Response
    {
      "success": true,
      "msg": "Successfully deleted the permission group: test",
      "id": -1
    }

PATH/<groupName>/roles

PATH/roles is a part of the primary PATH/group of Permission API alligned with two HTTP method (GET and POST) to make a unique operation for the resource to retieve the information correlated with the permissions associatd with the groups in the instance.

List of endpoints for the PATH/roles:

GET/get

This is a GET request API call to retrieve the list of roles assigned to the selected permissions group.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/roles/get
  • Server Response
    [
        "API",
        "Admin"
    ]

POST/add

This API endpoint call is to add a role to the selected permission group. This will be a POST method API call as we will have to attach the role in the body as a TEXT file to import into the Matillion ETL instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/roles/add WITH POST DATA arg0
  • POST BODY
    {
     "name":"Global"     
    }
  • Server Response
    {
      "success": true,
      "msg": "Successfully assigned the role [{\r\n \"name\":\"Global\"     \r\n}] to the group [Writer].",
      "id": -1
    }

POST/remove

This is a POST request API call to remove a role from the selected permission group.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/group/name/<groupName>/roles/remove WITH POST DATA arg0
  • POST BODY
    {
     "name":"Global"     
    }
  • Server Response
    {
      "success": true,
      "msg": "Successfully removed the role [{\r\n \"name\":\"Global\"     \r\n}] from the group [Writer].",
      "id": -1
    }

PATH/global

PATH/global is a part of the Permission API family with three HTTP method (GET and POST) and two PATH to make a unique operation for the resource to retieve the information correlated with the permissions associatd with the groups in the instance.

List of endpoints for the PATH/global:

GET/export

The is a GET operation for the resource information to export all the permissions for every group within the instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/global/export
  • Server Response
    {
        "objects": [
              {
                "group": "Example-Group",
                "permissions": {
                    "": "GRANTED",
                    "/OAuth": "GRANTED",
                    "/Variable": "GRANTED",
                    "/CDC": "GRANTED",
                    "/API Profile/Read": "GRANTED",
                    "/API Profile": "GRANTED",
                    "/Project": "GRANTED",
                    "/CDC/Read": "GRANTED",
                    "/CDC/Write": "GRANTED",
                    "/Credential": "GRANTED",
                    "/API Profile/Write": "GRANTED",
                    "/Queue": "GRANTED",
                    "/Password": "FORBIDDEN"
                }
            },
        ],
        "version": "1.44.11",
        "environment": "redshift"
    }

GET/group

This endpoint retrieve the list of all permsissions for every group in the instance, using GET REST API call.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/global/group
  • Server Response
    [
        "Example-Group",
        "Example-Group-2",
        "Admin only",
        "Reader",
    ]

POST/import

Now that you have an exported permission group (see previous example), this time we use the API to import the group 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/permission/global/import
  • POST BODY(JSON)
    {
        "objects": [
              {
                "group": "Example-Group",
                "permissions": {
                    "": "GRANTED",
                    "/OAuth": "GRANTED",
                    "/Variable": "GRANTED",
                    "/CDC": "GRANTED",
                    "/API Profile/Read": "GRANTED",
                    "/API Profile": "GRANTED",
                    "/Project": "GRANTED",
                    "/CDC/Read": "GRANTED",
                    "/CDC/Write": "GRANTED",
                    "/Credential": "GRANTED",
                    "/API Profile/Write": "GRANTED",
                    "/Queue": "GRANTED",
                    "/Password": "FORBIDDEN"
                }
            },
        ],
        "version": "1.44.11",
        "environment": "redshift"
    }
    
  • Server Response
    {
      "name": "Group Permissions",
      "statusList": [
        {
          "success": true,
          "name": "Example-Group"
        },
      ],
    }

PATH/instance

In the example below, we will be retrieving a single resource information, perform a GET request for that named resource endpoint. This PATH is a part of PATH/global URI which will retrieve the global list of groups for the instance.

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.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/global/instance?groupName=<groupName>
  • Server Response
    {
      "endpoints": [
        {
          "httpMethod": "PATH",
          "name": "GroupPermissionInstanceService",
          "children": [
            {
              "httpMethod": "GET",
              "name": "exportPermissions",
              "description": "Export all permissions for the selected group.",
              "path": "/export",
              "type": "ExportContainer<GroupPermissionContainerExport>",
              "example": "/export",
              "totalPath": "/export"
            },
            {
              "httpMethod": "GET",
              "name": "listPermissions",
              "description": "List permission in the selected group.",
              "path": "/permission",
              "type": "Set<String>",
              "example": "/permission",
              "totalPath": "/permission"
            },
              ],
              "children": [],
      "dataTypes": []
        } ]
    }

PATH/group/name/<groupName>

PATH/group/name{group} is a part of the PATH/global URI family with three HTTP method (GET and POST) and one PATH to make a unique operation for the resource to retieve the information correlated with the permissions associatd with the groups within the instance.

List of endpoints for the PATH/group/name/<groupName>:

GET/export

The is a GET operation for the resource information to export all the permissions for the selected group within the instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/global/group/name/<groupName>/export
  • Server Response
    {
        "objects": [
              {
                "group": "Example-Group",
                "permissions": {
                    "": "GRANTED",
                    "/OAuth": "GRANTED",
                    "/Variable": "GRANTED",
                    "/CDC": "GRANTED",
                    "/API Profile/Read": "GRANTED",
                    "/API Profile": "GRANTED",
                    "/Project": "GRANTED",
                    "/CDC/Read": "GRANTED",
                    "/CDC/Write": "GRANTED",
                    "/Credential": "GRANTED",
                    "/API Profile/Write": "GRANTED",
                    "/Queue": "GRANTED",
                    "/Password": "FORBIDDEN"
                }
            },
        ],
        "version": "1.44.11",
        "environment": "redshift"
    }

GET/permission

This endpoint retrieve the list of all permsissions alligned with the selected group within the instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/global/group/name/<groupName>/permission
  • Server Response
    [
        "Project",
        "Credential",
        "Variable",
        "CDC",
        "API Profile",
        "CDC-Write",
        "API Profile-Read",
        "CDC-Read",
        "Queue",
        "OAuth",
        "API Profile-Write",
        "Password"
    ]

POST/clear

The API call allows to reset permissions for the selected group within the Matillion ETL instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/global/group/name/<groupName>/clear
  • Server Response
    {
      "success": true,
      "msg": "Successfully reset the permissions for the group: Example-Group",
      "id": -1
    }

PATH/permission/name/<permissionName>

This PATH is a part of the PATH/group/name/<groupName> URI with two HTTP method (GET and POST) to make a unique operation for the resource to retieve or update the information correlated with the permissions associatd within the instance.

List of endpoints for the PATH/permission/name/<permissionName>:

GET/get

This endpoint is a GET request API call, that allows to retrieve the information of the selected permissions for the instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/permission/global/group/name/<groupName>/permission/name/<permissionName>/get
  • Server Response
    {
      "id": "/APIProfile",
      "state": "GRANTED"
    }

POST/update

The endpoint will update the state of selected permssions from the selected group within the instance. There are three permissions available within the Matillion ETL instance that includes: DEFAULT, GRANTED, FORBIDDEN. 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/permission/global/group/name/<groupName>/permission/name/<permissionName>/update WITH POST DATA arg0
  • POST BODY(JSON)
    {
          "id": "/APIProfile",
          "state": "FORBIDDEN"
    }
    

    Below is the description of the fields included in the POST body:

    Field Name Description
    id The name of the permission as available in instance.>
    state The new state to be changed (DEFAULT,FORBIDDEN,GRANTED).
  • Server Response
    {
        "success": true,
        "msg": "Successfully update the state of the permission: APIProfile",
        "id": 0
    }