API v1 - Permission

Overview

This guide provides details on the Permission API services offered by Matillion ETL. The Permission API gives details on permissions that either allow or restrict access to each group in Matillion ETL.

The Permissions in Matillion ETL allow admins to specify what parts of the client each user has access to or restrictions, 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.

The 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. The Permissions API family consist of some PATHs that combine with endpoint resources using HTTP methods: GET, POST, and DELETE.

Permission API Endpoints

API Base URL

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

API Endpoints and Function

The 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:

Graphical Representation

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

URL Parameters and Description

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

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 permissions to access within the Matillion ETL instance.

Before working with any Permission endpoint call, we recommend that you understand the concept of PATH used in the Permission API family.

A PATH is a unit of a REST API that you can call. A PATH comprises HTTP Methods (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:

• PATH/user
• PATH/user/name/<userName>groups
• PATH/group
• PATH/group/roles
• PATH/global
• PATH/instance
• PATH/group/name/<groupName>
• PATH/permission/name/<permissionName>

The graphical view of the Permission API PATHs shown below:

Once you have a 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.

List of endpoints for the PATH/user:

• GET/user
• GET/user/export
• POST/user/import
• POST/userName/delete
• GET/userName/group/id
• GET/userName/group/get
• GET/userName/group/add
• POST/userName/group/remove

GET/user

To get the list of users for the specified permission. This example using GET method REST API call to export the permission users.

• Base URL

  http://<InstanceAddress>/rest/v1/permission/user

• Server Response

  [
  "user-1"
  "user-2"
  "user-3"]

GET/export

To export the list of users for the specific permission from one instance to another using /export endpoint. This example using GET method REST API call to export the permission groups and all associated information aligned with the groups.

• Base URL

  http://<InstanceAddress>/rest/v1/permission/user/export

• Server Response

  {
  "objects": [
  {
  "name": "automation-user",
  "groupNames": []
  },
  {
  "name": "ss-docs",
  "groupNames": []
  }
  ],
  "version": "Built",
  "environment": "redshift"
  }

POST/import

The /import endpoint imports one or more permission user. This example uses the POST method REST API call to import the permission users to the 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/user/import

• POST BODY(JSON)

  {
  "objects": [
  {
  "name": "User-1",
  "groupNames": []
  },
  {
  "name": "User-2",
  "groupNames": []
  }
  ],
  "version": "Built",
  "environment": "redshift"
  }
  

• Server Response

  {
  "name": "Permission Users",
  "statusList": [
  {
  "success": true,
  "name": "User-1"
  },
  {
  "success": true,
  "name": "User-2"
  }
  ],
  "success": true
  }

• URL Parameters

  There is an optional parameter, onConflict, which determines what should happen if an import clashes with something that already exists. For an explanation of this parameter's use, read API Import conflicts - Explanation in Matillion ETL API - v1.

POST/userName/delete

Delete the selected permission user from the instance.

• Base URL
  

  http://<InstanceAddress>/rest/v1/permission/user/name/userName/delete



• Server Response
  

  {
  
  "success": true,
  
  "msg": "Successfully deleted the permission user by the name: User-1",
  
  "id": -1
  
  }

PATH/user/name/<userName>/groups

GET/userName/groups/ids

To get the set of group IDs assigned to the selected permission user. This example uses the GET method REST API call to export the groups' ids assigned to the user.

• Base URL
  

  http://<InstanceAddress>/rest/v1/permission/user/name/userName/groups/ids



• Server Response
  

  [
  
  2138489
  
  ]

GET/userName/groups/get

Get the set of group names assigned to the selected permission user. This example uses the GET method REST API call to get the groups assigned to the user.

• Base URL
  

  http://<InstanceAddress>/rest/v1/permission/user/name/userName/groups/get



• Server Response
  

  [
  
  "Runner",
  
  "Scheduler",
  
  "Reader with Comments",
  
  "All Global Access",
  
  "Reader",
  
  "Writer"
  
  ]

POST/userName/groups/add

This is to add a group to the selected permission user. If a resource of the same name already exists, you must delete the existing resource before adding the new. This will be a POST method API call as we will have to attach the details in the body as a JSON to add a group into the instance.

• Base URL
  

  http://<InstanceAddress>/rest/v1/permission/user/name/userName/groups/add



• POST Body (JSON)
  

  [
  
  "name": "Test"
  
  ]



• Server Response
  

  {
  
  "success": true,
  
  "msg": "Successfully added the group permission Test to the group.",
  
  "id": -1
  
  }

POST/userName/groups/remove

This is to remove a group from the selected permission group .

http://<InstanceAddress>/rest/v1/permission/user/name/userName/groups/remove

{

"success": true,

"msg": "Successfully removed the group permission Test.",

"id": -1

}

PATH/group

PATH/group is a primary PATH for the API Base URL of Permission API aligned with HTTP methods (GET, POST, DELETE), and a PATH to make a unique operation for the resource to retrieve the information correlated with the permissions associated with the groups in the instance.

List of endpoints for the PATH/group:

• GET/export


• POST/import


• GET/parent


• GET/groupName/export


• DELETE/groupName


• POST/update


• POST/delete


• PATH/roles

GET/export

To export one or more permission groups within the Matillion instance, use /export endpoint. This example uses the GET method REST API call to export the permission groups and all associated information aligned with the groups.

• Base URL
  

  http://<InstanceAddress>/rest/v1/permission/group/export



• Server Response
  

  {
  
  "objects": [
  
  {
  
  "name": "Writer",
  
  "otherRoles": [],
  
  "parentGroupID": null
  
  },
  
  {
  
  "name": "NoEnterprise",
  
  "otherRoles": [],
  
  "parentGroupID": null
  
  },
  
  {
  
  "name": "Runner",
  
  "otherRoles": [],
  
  "parentGroupID": null
  
  }.....
  
  ],
  
  "version": "1.48.7",
  
  "environment": "redshift"
  
  }

POST/import

Now that you have an exported permission group (see previous example), we'll use the API to import one or more permission groups 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/group/import



• POST BODY(JSON)
  

  {
  
  "objects": [
  
  {
  
  "name": "Docs",
  
  "otherRoles": [],
  
  "parentGroupID": null
  
  }
  
  ],
  
  "version": "1.48.7",
  
  "environment": "redshift"
  
  }
  
  

  
  


• Server Response
  

  {
  
  "name": "Permission Groups",
  
  "statusList": [
  
  {
  
  "success": true,
  
  "name": "Docs"
  
  }
  
  ],
  
  "success": true
  
  }



• URL Parameters

  There is an optional parameter, onConflict, which determines what should happen if an import clashes with something that already exists. For an explanation of this parameter's use, read API Import conflicts - Explanation in Matillion ETL API - v1.

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/<groupName>/export

To export the all group permissions within the instance, provide the groupName and use the /export endpoint. This example uses the GET method REST API call to export the selected permission group and all associated information aligned 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, use the DELETE API request. In this example, we'll delete a permission group from within the permissions in the Matillion ETL instance.

• 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 you'll need 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	Data type	Description
  name	String	The name of the permission group.
  otherRoles	String	The new role if required to be added.
  parentGroupID	String	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 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 aligned with two HTTP method (GET and POST) to make a unique operation for the resource to retrieve the information correlated with the permissions associatd with the groups in the instance.

List of endpoints for the PATH/roles:

• GET/get
• POST/add
• POST/remove

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\
  \\"name\\":\\"Global\\"     \\r\
  }] 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\
  \\"name\\":\\"Global\\"     \\r\
  }] from the group [Writer].",
  "id": -1
  }

PATH/global

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

List of endpoints for the PATH/global:

• GET/export
• GET/group
• POST/import
• PATH/instance
• PATH/group/name/<groupName>

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), we'll 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

We'll be retrieving a single resource information, performing a GET request for that named resource endpoint. This PATH is a part of the PATH/global URI which will retrieve the global list of groups for the instance.

When 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 twto HTTP methods (GET and POST), and one PATH, for the resource to retrieve the information correlating with the permissions of the groups within the instance.

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

• GET/export
• GET/permission
• POST/clear
• PATH//permission/name/<permissionName>

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 retrieves the list of all permissions aligned 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

This API call lets you 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 methods (GET and POST), to make a unique operation for the resource to retrieve or update the information associated within the instance.

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

• GET/get
• POST/update

GET/get

This endpoint is a GET request API call that lets you 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 permissions from the selected group within the instance. There are three permissions in Matillion ETL instance: 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	Data type	Description
  id	String	The name of the permission as available in instance.
  state	String	The new state to be changed. Must be one of: DEFAULT, FORBIDDEN, or GRANTED.

• Server Response

  {
  "success": true,
  "msg": "Successfully update the state of the permission: APIProfile",
  "id": 0
  }