Skip to content

API v1 - API Profiles

The API Profile endpoint allows the API to view the Extract and Query Profiles created in your Matillion ETL instance. The data is returned unflattened or nested in the form of a single-column JSON structure. As part of this endpoint, you can do the following:

  • Export and import more than one API Profile and/or RSD files contained in your Matillion ETL instance.
  • Test the validity of the RSD file in your chosen API Profile.
  • Revert the specified RSD file to the original version.
  • Delete the RSD file from the chosen API Profile in your Matillion ETL instance.

Prerequisites

  • 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.
  • If you are new to Matillion ETL's API, read our Matillion API introduction and explore the v1 API map.
  • 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.

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.
  • Matillion ETL can currently only use API Profiles and RSD files that are formatted in JSON.

Using the API

Return API Extract and Query Profiles in a Matillion ETL instance by making a GET or POST call with the form:

<InstanceAddress>/rest/v1/apiprofile/<endpoint>

Note

<InstanceAddress>/rest/v1/apiprofile is the base URI for all API extract profile endpoints. Add the specific information for each function, documented in the below sections.

Where:

  • <instanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <endpoint> is the name of the API endpoint that accomplishes the task you want to perform. These endpoints are documented in the following sections.

GET apiprofile

Returns a list of API Profile names in this Matillion ETL instance.

To return a list of API Profile names, make the following GET call:

<InstanceAddress>/rest/v1/apiprofile

A successful GET call to the endpoint will return the following response from the server, in JSON format:

{
    "Facebook",
    "Google Adwords",
    "Google Analytics",
    "Jira",
    "Matillion API",
    "Mixpanel",
    "Sample",
    "Twitter",
    "Zendesk",
    "Zuora"
}

GET file

Returns a list of the RSD files in the specified API Profile.

To return a list of RSD files, make the following GET call:

<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file

Where <ProfileName> is the name of an API Profile in this Matillion ETL instance that you want to retrieve the file list for.

A successful GET call to the endpoint will return the following response from the server, in JSON format:

{
    "NorthwindOData.rsd",
    "NorthwindOData.xml"
}

GET export

Exports one or more API Profiles, and/or their RSD files from this Matillion ETL instance.

To export the entire list of API Profiles, and/or their RSD files, make the following GET call:

<InstanceAddress>/rest/v1/apiprofile/export

To export a single API Profile, make the following GET call:

<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/export

Where: <ProfileName> is the name of the API Profile created in this Matillion ETL instance.

To export a single named RSD file, make the following GET call:

<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/name/<RSDFile>/export

Where:

  • <ProfileName> is the name of the API Profile created in this Matillion ETL instance.
  • <RSDFile> is the name of the RSD file specified in the chosen API Profile.

A GET call to the endpoint will return the following response from the server for a single API extract profile, in JSON format:

        {
            "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

Import one or more API Profiles, and/or their RSD files into this Matillion ETL instance.

To import the entire list of API Profiles, make the following POST call:

<InstanceAddress>/rest/v1/apiprofile/import

To import a single API Profile, make the following POST call:

<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/import

Where <ProfileName> is the name of the API Profile created in this Matillion ETL instance.

To import an RSD file from a specified API Profile, make the following POST call:

<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/name/<RSDFile>/import

Where:

  • <ProfileName> is the name of the API Profile created in this Matillion ETL instance.
  • <RSDFile> is the name of the RSD file specified in the chosen API Profile.

To import an RSD file from a specified API Profile, the POST body should contain the following, in JSON format:

        {
            "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"
        }
  • <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 instance 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.

A successful POST call to the endpoint will return the following response from the server, in JSON format:

{
    "name": "API Profile Files",
    "statusList": [
        {
            "success": true,
            "name": "NorthwindOData.rsd"
        }
    ],
    "success": true
}

GET test

Test the validity of the specified API Profile's RSD file, in this Matillion ETL instance.

To test the RSD file, make the following GET call:

<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/<RSDFile>/test

Where:

  • <ProfileName> is the name of the API Profile created in this Matillion ETL instance.
  • <RSDFile> is the name of the RSD file specified in the chosen API Profile.

A successful GET call to the endpoint will return the following response from the server, in JSON format:

{
    "success": false,
    "msg": "Testing was unsuccessful for the file: Sample. No columns were returned.",
    "id": -1
}

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

Revert the RSD file back to the original version prior to editing, outside of this Matillion ETL instance.

To revert the RSD file, make the following POST call:

<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/<RSDFile>/revert

Where:

  • <ProfileName> is the name of the API Profile created in this Matillion ETL instance.
  • <RSDFile> is the name of the RSD file specified in the chosen API Profile.

A successful POST call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully reverted the file: AdCreatives.rsd.",
    "id": -1
}

POST delete

Delete the RSD file from the specified API Profile in this Matillion ETL instance.

<InstanceAddress>/rest/v1/apiprofile/name/<ProfileName>/file/<RSDFile>/delete

Where:

  • <ProfileName> is the name of the API Profile created in this Matillion ETL instance.
  • <RSDFile> is the name of the RSD file specified in the chosen API Profile.

A successful POST call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully deleted the file: NorthwindOData.rsd.",
    "id": -1
}
© Copyright 2024 Matillion Ltd | Legal | Privacy Policy | Disclaimer | Modern Slavery Statement