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
Where:
<instanceAddress>is the URI of your Matillion ETL instance in the formhttp://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
}