API v1 - Passwords
    • Dark
      Light

    API v1 - Passwords

    • Dark
      Light

    Article Summary

    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:

    Group endpoint PATHs

    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 target="_blank">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:

    MethodPathURIFunction
    GET/namehttp://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/nameGet the name of the password.
    GET/idhttp://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/idGets the ID of the password.
    GET/gethttp://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/getReturns the password.
    GET/exporthttp://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/exportExport the given password.
    POST/deletehttp://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/deleteDelete the given password.
    POST/updateFromExporthttp://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/updateFromExport WITH POST DATA arg0Supply password as already encoded since password will be created as is.
    POST/createhttp://<instance address>/rest/v1/group/name/<groupname>/password/createSupply password as plaintext to be Encoded by standard set in EncryptionType.
    POST/importhttp://<instance address>/rest/v1/group/name/<groupname>/password/importImport password via ExportContainer. Supply password as already encoded since password will be created as is.​
    POST/updatehttp://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordName>/update WITH POST DATA arg0Supply password as plaintext as it will encode via encryptionType provided.
    DELETE/passwordNamehttp://<instance address>/rest/v1/group/name/<groupname>/password/name/<passwordNameTo 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 NameDescription
    <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:

    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 nameData typeDescription
      nameStringAn arbitrary name of the password.
      passwordStringProvide an arbitrary password.
      masterKeyStringAn AWS KMS Master Key that will be used to encrypt the password. It can be same as you get in exporting the password detail.
      descriptionStringAn optional description of this password.
      encryptionTypeStringChoose between "ENCODED" and the key management service the platform offers ("KMS" or "KVS"). Preferably keep as "ENCODED"
      extraInfoStringSome 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
      }