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.
:::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
}
```