Skip to content

API v1 - API Profile

Overview

The API Profile endpoint allows API Profiles to be managed externally, similarly to how they're managed within Matillion ETL. To begin, click Project, then Manage API Profiles. API Profiles—and the RSD files contained within them—can then be exported and imported via the API Profile endpoint.

:::info{title='Note'}

  • 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 user's username and password, with appropriate permissions; and 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

The API Profile API is available on standard REST-based APIs that use 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 /apiprofile https://<InstanceAddress>/rest/v1/apiprofile List all API profiles in the Matillion ETL instance.
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 API Profile endpoints further, below is the graphical flow of the /apiprofile endpoint showing possible methods GET, POST, and DELETE.

APIProfile API endpoint Flow

:::info{title='Note'}

  • The username and password of a user with access to the API Profiles within a 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 API method for specifically exporting or importing 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 that are 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, acquired by running an API call: http://<instance address>/rest/v1/apiprofile.
<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 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\
        \r\
          \r\
            \r\
             \r\
            \r\
            \r\
            \r\
            \r\
            \r\
            \r\
            \r\
            \r\
            \r\
            \r\
            \r\
            \r\
            \r\
            \r\
          \r\
        \r\
          \r\
          \r\
            \r\
          \r\
            \r\
              \r\
            \r\
          \r\
          \r\
        ",
                    "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

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

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

Field name Data Type Description
name String The name of the API Profile or RSD file imported.
contents String The contents of the API Profile or RSD file imported.
version String The version of Matillion ETL into which the API Profile or RSD file was imported.
environment String 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
        }

:::info{title='Note'} The /test function makes a very limited API call to the service to evaluate the validity of the API Profile. However, it's recommended for only testing API Profiles within Matillion ETL, because 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
    ``` copy-text
    {
      "success": true,
      "msg": "Successfully deleted the file: NorthwindOData.rsd.",
      "id": -1
    }
    ```