API v1 - API Profile

API v1 - API Profile


Overview

The apiprofile endpoint allows API Profiles to be managed externally, similarly to how they are managed within the Matillion ETL client via Project Menu Manage API Profiles. API Profiles, and the RSD files contained within them, can then be exported and imported by going through that specific, existing API Profile's endpoint.

Important Information

  • This document is part of a series on API Profiles and the Matillion ETL v1 API
  • This process requires the Matillion ETL instance URL, the username and password of a user with appropraite permissions, as well as the name of the API Profile and / or RSD file to be exported or imported.

API Profile API Endpoints

API Base URL

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

API Endpoints and Function

API Profile API is available on standard REST-based APIs that uses a HTTP or HTTPS request to GET and POST data. The API Profile 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 URL Function
GET /export https://<InstanceAddress>/rest/v1/apiprofile/export Export one of more API Profiles
POST /import https://<InstanceAddress>/rest/v1/apiprofile/import Import one or more API Profiles
GET /test https://<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/test Test an API Profile
GET /file https://<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file List all RSD files in an API Profile
POST /delete https://<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/name/<RSDFile>/delete Delete an RSD file
POST /revert https://<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/name/<RSDFile>/revert Revert an RSD file

Graphical Representation

To illustrate the APIProfile API, endpoints to the further, below is the graphical flow of the /apiprofile endpoint showing possible methods GET, POST, and DELETE .

APIProfile API endpoint Flow

APIProfile API endpoint Flow

Please Note

  • The username and password of a user with access to the API Profiles within Matillion ETL instance will need to be used to authenticate the connection. These may need to be specified before the command when using a command line tool—for example: -u user:password.
  • When exporting or importing API Profiles or RSD files, the source file or content type and target file will also need to be specified.
  • There is no method to specifically export or import all RSD files in an API Profile, as this can be done when exporting or importing the API Profile itself.
  • Matillion ETL can currently only use API Profiles and RSD files formatted in JSON.

API Parameters and Description

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

Parameter Description
<InstanceAddress> The server IP address or domain name of the Matillion ETL instance
<name> This allows an API Profile or RSD file to be specified by the name used in the Matillion ETL instance.
<ProfileName> The name of the API Profile created in the Matillion ETL instance—alternatively, list of all the API Profiles in the Matillion ETL instance by running an API call: http://<intance address>/rest/v1/aprprofile
<file> List all RSD files within the specified API Profile
<RSDFile> The name of an RSD file within the specified API Profile
<export> This allows the API to export the Queue configuration to another Matillion ETL instance
<import> This allows the API to import the Queue configuration from another Matillion ETL instance
<test> This allows the API to test the validity of the API Profile
<revert> This allows the API to revert an RSD file back to its original state
<delete> This allows the API to delete an RSD file

Endpoints and Server Response

These APIs provide a REST-based web service—offering ease of use and a flexible choice of programming language—and can be used to access and analyse data and service provider content. Below are a number of example endpoints along with the corresponding summary, parameters and server responses:

GET/apiprofile

This endpoint permits the API to list all the API profiles from the Matillion ETL instance.

  • Base URL
    https://<InstanceAddress>/rest/v1/apiprofile
  • Server Response
    [
        "Facebook",
        "Google Adwords",
        "Google Analytics",
        "Jira",
        "Matillion API",
        "Mixpanel",
        "Sample",
        "Twitter",
        "Zendesk",
        "Zuora"
    ]

GET/file

This endpoint permits the API to list the RSD files within the specified API Profile.

  • Base URL
    https://<InstanceAddress>/rest/v1/apiprofile/name/Sample/file
  • Server Response
    [
        "NorthwindOData.rsd",
        "NorthwindOData.xml"
    ]

GET/export

This endpoint permits the API to export one or more API Profiles and / or their RSD files from the Matillion ETL instance.

  • Base URL
    https://<InstanceAddress>/rest/v1/apiprofile/export
    https://<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/export
    https://<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/name/<RSDFile>/export
  • Server Response
    {
        "objects": [
            {
                "name": "NorthwindOData.rsd",
                "contents": "\r\n\r\n  \r\n    \r\n     \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n  \r\n\r\n  \r\n  \r\n    \r\n  \r\n    \r\n      \r\n    \r\n  \r\n  \r\n",
                "truncated": false,
                "uploaded": false
            }
        ],
        "version": "1.44.11",
        "environment": "bigquery"
    }

POST/import

This endpoint permits the API to import one or more API Profiles and / or their RSD files into the Matillion ETL instance. This will be a "POST" method API call as it will have to attach the project, in the body as a JSON file to import into the Matillion ETL instance.

  • Base URL
    https://<InstanceAddress>/rest/v1/apiprofile/import
    https://<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/import
  • POST Body (JSON)
    {
        "objects": [
            {
                "name": "NorthwindOData.rsd",
                "contents": "\r\n\r\n  \r\n    \r\n     \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n    \r\n  \r\n\r\n  \r\n  \r\n    \r\n  \r\n    \r\n      \r\n    \r\n  \r\n  \r\n",
                "truncated": false,
                "uploaded": false
            }
        ],
        "version": "1.44.11",
        "environment": "bigquery"
    }

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

    Field name Description
    name The name of the API Profile or RSD file imported
    contents The contents of the API Profile or RSD file imported
    version The version of Matillion ETL into which the API Profile or RSD file was imported
    environment The cloud data warehouse environment into which the API Profile or RSD file was imported
  • Server Response
    {
      "name": "API Profile Files",
      "statusList": [
        {
          "success": true,
          "name": "NorthwindOData.rsd"
        }
      ],
      "success": true
    }

GET/test

This endpoint permits the API to test the validty of the RSD file within the specified API Profile on the Matillion ETL instance.

  • Base URL
    https://<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/<RSDFile>/test
  • Server Response
    {
      "success": false,
      "msg": "Testing was unsuccessful for the file: Sample. No columns were returned.",
      "id": -1
    }

    Please Note

    The /test function makes a very limited API call to the service to evaluate the validity of the API Profile. However, it is recommended only testing API Profiles from within Matillion ETL as this function may return invalid test results due to authentication requirements or empty API Profiles.

POST/revert

This endpoint permits the API to revert the RSD file back to the original version prior to editing outside of the Matillion ETL instance.

  • Base URL
    https://<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/<RSDFile>/revert
  • Server Response
    {
      "success": true,
      "msg": "Successfully reverted the file: AdCreatives.rsd.",
      "id": -1
    }

POST/delete

This endpoint permits the API to delete the RSD file from the API Profile in the Matillion ETL instance.

  • Base URL
    https://<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/<RSDFile>/delete
  • Server Response
    {
      "success": true,
      "msg": "Successfully deleted the file: NorthwindOData.rsd.",
      "id": -1
    }