API v1 - Passwords

Overview

This is a guide to providing details on the Password API from the family of the Group API . The Password endpoint allows users to explore and manage the passwords of the Project Group within the Matillion ETL. Passwords are stored at the Project Group level and thus will be shared with, and accessible from, all other projects within that same group.

Password API (PATH/password) is a part of the /group API as shown below:

Passwords are typically managed using Password Manager through Project Menu , then Manage Passwords inside the Matillion ETL client. It is, however, possible to perform many similar functions through the v1 API.

Manage Passwords

The Password API provides the "resource" details within the Project Group of your Matillion ETL instance. By "resources", we refer to exploring and managing the passwords, such as get and list, export/import and update, delete, and create a new password within your Matillion ETL instance. The Password endpoint is the part of the /group API family with many endpoints that include HTTP methods (GET, POST, and DELETE) for unique combinations to get the "resource" information for your Matillion ETL instance.

Important Information

This document is part of a series on API v1 - Group and the Matillion ETL API - v1.
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.
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.

Password API Endpoints

API Base URL

http(s)://<InstanceAddress>/rest/v1/group/name/<groupName>/password

API Endpoints and Function

Password API endpoint is available on standard REST-based APIs that uses HTTP or HTTPS request to GET, POST, and DELETE data. The Password API service is accessed through the Uniform Resource Identifier (URI). The available API endpoints are listed below:

Method	Path	URI	Function
GET	/name	http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/name	Get the name of the password.
GET	/id	http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/id	Gets the ID of the password.
GET	/get	http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/get	Returns the password.
GET	/export	http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/export	Export the given password.
POST	/delete	http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/delete	Delete the given password.
POST	/updateFromExport	http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/updateFromExport WITH POST DATA arg0	Supply password as already encoded since password will be created as is.
POST	/create	http://<instance address>/rest/v1/group/name/<groupname>/password/create	Supply password as plaintext to be Encoded by standard set in EncryptionType.
POST	/import	http://<instance address>/rest/v1/group/name/<groupname>/password/import	Import password via ExportContainer. Supply password as already encoded since password will be created as is.
POST	/update	http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/update WITH POST DATA arg0	Supply password as plaintext as it will encode via encryptionType provided.
DELETE	/passwordName	http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName	To delete the selected version using DELETE HTTP method.

Graphical Representation

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

Password endpoint Flow

URL Parameters and Description

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

Parameters Name	Description
<instance address>	This is the server IP address or domain name.
<groupName>	The name of the group.
<passwordName>	The name of the password available within the Project Group.
<export>	This allows to export the metadata of the resource.
<import>	This allows to import the metadata of the resource.
<delete>	Delete the selected resource.
<id>	The queue id of the current resource.
<name>	The name of the selected resource.
<create>	To create a new resource using POST body.
<update>	To update or supply the resource details using POST body.

Endpoints and Server Response

This chapter describes the Password API endpoints with examples. These APIs offers REST-based web service, offering ease of use and a flexible choice of programming language.

All the APIs listed in this chapter are available to use with GET/POST/DELETE methods to retrieve the data used to get, update, import/export, create or delete the passwords within the Project Group.

List of endpoints for the /password:

GET/name
GET/id
GET/get
GET/export
POST/delete
POST/updateFromExport
POST/create
POST/import
POST/update
DELETE/passwordName

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

GET/name

This is a GET method REST API request that will provide the name of the password within the Project Group of the Matillion ETL instance.

Base URL

http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/name

Server Response
```
API PROJECT-test
```

GET/id

This is to get the ID of the selected password from the the current Project Group. The API call is a GET HTTP method request to fetch the detail.

Base URL

http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/id

Server Response
```
71682
```

GET/get

This API call is a GET HTTP method request that returns with the password detail, such as id, name, encyryprionType, password and description.

Base URL

http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/get

Server Response

{
  "id": 71682,
  "name": "API PROJECT-test",
  "password": "",
  "encryptionType": "ENCODED",
  "description": "Password for environment [test]."
}

GET/export

To export the password, provide the /passwordName and use the /export endpoint. This will export the selected password using GET HTTP method call request.

Base URL

http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/export

Server Response

{
    "objects": [
        {
            "name": "API PROJECT-test",
            "password": "",
            "masterKey": null,
            "description": "Password for environment [test].",
            "encryptionType": "ENCODED",
            "extraInfo": null
        }
    ],
    "version": "master",
    "environment": "redshift"
}

POST/delete

This will be a POST method API call. The /delete endpoint will allow to delete the selected password from the Project Group in the instance.

Base URL

http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/delete

Server Response

{
  "success": true,
  "msg": "Successfully deleted the password: API PROJECT-test",
  "id": -1
}

POST/updateFromExport

Supply password as already encoded and password will be created as is. This will be a POST method API call as we will have to attach the variable for the passwords to be queued, in the body as a JSON file to run into the Matillion ETL instance.

Base URL

http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/updateFromExport WITH POST DATA arg0

POST Body

{
            "name": "API PROJECT-test",
            "password": "test",
            "masterKey": null,
            "description": "Password for environment [test].",
            "encryptionType": "ENCODED",
            "extraInfo": null
        }

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

Field name	Data type	Description
name	String	An arbitrary name of the password.
password	String	Provide an arbitrary password.
masterKey	String	An AWS KMS Master Key that will be used to encrypt the password. It can be same as you get in exporting the password detail.
description	String	An optional description of this password.
encryptionType	String	Choose between "ENCODED" and the key management service the platform offers ("KMS" or "KVS"). Preferably keep as "ENCODED"
extraInfo	String	Some additional description if needed.

Server Response

{
  "success": true,
  "msg": "Successfully updated password: API PROJECT-test.",
  "id": 71682
}

Please Note

Modifying the "Password Name" is not allowed in POST Body, please keep the password name same as in URL <passwordName>

POST/create

This is to supply password as plaintext to be Encoded by standard set in EncryptionType.

Base URL

http://<instance address>/rest/v1/group/name/<groupname>/password/create

POST Body

{
            "name": "test-password",
            "password": "test01",
            "masterKey": null,
            "description": "Password for environment [test].",
            "encryptionType": "ENCODED",
            "extraInfo": null
}

Server Response

{
  "success": true,
  "msg": "Successfully created password: test-password",
  "id": 66329
}

Please Note

The description of the field names used in POST body, please refer the section above.

POST/import

Now you have already export the password in the example before. This time is to import password via ExportContainer. Supply password as already encoded since password will be created as is. This will be a POST method API call as we will have to attach the variable for the password to be imported, in the body as a JSON file to run into the Matillion ETL instance.

Please Note

If a resource of the same name already exists, you must delete the existing resource before importing the new or you can change the name of the imported resource (passwordImported) in the POST BODY.

Base URL

http://<instance address>/rest/v1/group/name/<groupname>/password/import

POST Body

{    
    "objects": [
        {
            "name": "PasswordImported",
            "password": "test",
            "masterKey": null,
            "description": "Password for environment [test].",
            "encryptionType": "ENCODED",
            "extraInfo": null
        }
    ],
    "version": "master",
    "environment": "redshift"
}

Server Response

{
  "name": "Passwords",
  "statusList": [
    {
      "success": true,
      "name": "PasswordImported"
    }
  ],
  "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.

Please Note

The description of the field names used in POST body, please refer the section above.

POST/update

The POST HTTP method API call request is to supply password as plaintext as it will encode via encryptionType provided.

Base URL

http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/update WITH POST DATA arg0

POST Body

{
            "name": "API PROJECT-test",
            "password": "test01",
            "masterKey": null,
            "description": "Password for environment [test].",
            "encryptionType": "ENCODED",
            "extraInfo": null
}

Server Response

{
  "success": true,
  "msg": "Successfully updated password: API PROJECT-test.",
  "id": 71682
}

Please Note

Modifying the "Password Name" is not allowed in POST Body, please keep the password name same as in URL <passwordName>

For the description of the field names used in POST body, please refer the section above.

DELETE/passwordName

The DELETE HTTP request will allow to delete the selected password from the Project Group within the instance.

Base URL

http://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>

Server Response

{
  "success": true,
  "msg": "Successfully deleted password: API PROJECT-test",
  "id": 0
}