API v1 - OAuth

API v1 - OAuth


Overview


This is a guide to providing details on the OAuth API services offered by Matillion ETL. These services allow data to be imported from the service providers such as Facebook, Salesforce, Hubspot, BingAds and many more using OAuths, alongside the working environment and supporting resources. It covers all the stages to interact with OAuth API endpoints and services, from initial interest through the end of use. The OAuth API is built on the Matillion ETL instance, which allows users to easily discover, integrate, analyse, enrich and consume the content through a single, consistent interface.


When importing data into a table from a number of services it is necessary to use OAuth as the authentication mechanism. Matillion ETL abstracts the OAuth setup for all OAuth API’s to make this process as easy as possible.



Important Information and Links


Please take note of the following information before getting started:



  • Users responsible for experimenting with OAuth API services require access to the Matillion ETL instance and should know how to make REST API calls either using a GUI client such as Postman or using a command-line interface like cURL.

  • For more information about accessing the Matillion API, and general information on the Matillion API platform before using the OAuth API, please refer to Matillion API introduction.

  • Data Stagers with the following OAuth article, will be required to go through the Manage OAuth menu in the Matillion ETL client. Please refer to Manage OAuth article for a general description of how to add the OAuth in Matillion ETL instance. However, it is recommend searching the Matillion documentation for the specific "Authentication Guide" required.

  • Matillion ETL API endpoints require authorisation to make any REST API call, so ensure a username and password for the Matillion ETL instance is configured before making any API call.




OAuth API Endpoints



OAuth API is available on standard REST-based APIs that uses HTTP or HTTPS request to GET, POST, and DELETE data.The OAuth 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 Description
GET /properties http://<instance address>/rest/v1/oauth/name/<OAuth name>/properties Get the properties of the selected OAuth.
POST /import http://<instance address>/rest/v1/oauth/import Import one or more OAuths.
GET /id http://<instance address>/rest/v1/oauth/name/<OAuth name>/id Get the ID of the selected OAuth.
GET /name http://<instance address>/rest/v1/oauth/name/<OAuth name>/name Get the name of the selected OAuth.
GET /type http://<instance address>/rest/v1/oauth/name/<OAuth name>/type Get the type of the selected OAuth.
GET /status http://<instance address>/rest/v1/oauth/name/<OAuth name>/status Get the status of the selected OAuth.
GET /settings http://<instance address>/rest/v1/oauth/name/<OAuth name>/settings Get the settings of the selected OAuth.
POST /delete http://<instance address>/rest/v1/oauth/name/<OAuth name>/delete Delete the selected OAuth.
GET /export http://<instance address>/rest/v1/oauth/name/<OAuth name>/export Export the current OAuth.
DELETE /OAuthname http://<instance address>/rest/v1/oauth/name/<OAuth name> Delete the selected OAuth from the server.



API Parameters and Description

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

Parameters Name Description
<instance address> This is the server IP address or domain name.
<OAuth name> The name of the OAuth, you have created in Matillion ETL instance Manage OAuth. Alternatively, you can find the list of OAuths in the Matillion ETL instance by running an API call: http://<server address>/rest/v1/oauth
<properties> These are the properties associated with the choosen OAuth. This property will get the detail of the selected OAuth, for example: CallbackURL, AccountId, AccessToken, Clientsecret, ClientId, DeveloperToken, CustomerId, Verifier and other information.
<import> This allows to import the OAuths to the another instance. You need to provide the OAuth information which you would like to import .
<id> This property provides the id associated with the selected OAuth.
<name> This property gives the name of the selected OAuth. The name of the OAuth in the Matillion ETL.
<type> This provides the type of the selected OAuth.
<status> This gives the status of the selected OAuth. "Configured" or "Not Configured".
<settings> This gives the settings message of the selected OAuth.
<delete> This property will delete the selected OAuth.
<export> This property allows to export the selected OAuth from one instance to another.



Endpoints and Server Response

This chapter describes the OAuth APIs endpoints and examples. These APIs offers REST-based web service, offering ease of use and a flexible choice of programming language. These APIs can be used to access and analyse data and service provider content. All the APIs listed in this chapter are available to use with GET/POST/DELETE methods to retrieve the data used to view or delete the OAuth. For each API endpoint, the corresponding summary, parameters, responses and examples are provided:

GET/properties


Summary

This endpoint permits the API to recover the properties of the chosen OAuth. The properties of the OAuth incorporates:CallbackURL, AccountId, AccessToken, Clientsecret, ClientId, DeveloperToken, CustomerId, Verifier, settings and other data.

Base URL

http://<instance address>/rest/v1/oauth/name/<OAuth name>/properties

Server Response

{
"CallbackURL": "<OAuth Redirect URL>",
"RefreshToken": "<Refresh Token>",
"ClientSecret": "<Client Secret>",
"AccessToken": "<Access Token>",
"ClientID": "<Client ID>",
"Verifier": "<OAuth Verifier>",
"OrganizationUrl": "<OAuth Organization url>"
}

POST/import


Summary

This endpoint permits the API to import one or more OAuths into the Matillion ETL instance. This will be a "POST" method API call as we will have to attach the project (in jSON form, as exported), in the body as a JSON file to import into the Matillion ETL instance.

Base URL

http://<instance address>/rest/v1/oauth/import

POST Body(JSON)

{
    "objects": [
        {
            "name": "ExampleOAuth",
           "serviceID": 12,
           "properties": {
                  "CallbackURL": "<OAuth Redirect URL>",
                  "RefreshToken": "<Refresh Token>",
                  "ClientSecret": "<Client Secret>",
                  "AccessToken": "<Access Token>",
                  "ClientID": "<Client ID>",
                  "Verifier": "<OAuth Verifier>",
   	            "OrganizationUrl": "<OAuth Organization url>"
            },     
		]   
}

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

Field name Description
Name The name of the OAuth you wanted to add into the Matillion ETL.
ServiceID Unique identifier assigned to the OAuth.
CallbackURL Callback URL that used to send and recieve the data invokes after the authentication process with Matillion ETL.
RefreshToken Token used to obtain a renewed Access Token.
ClientSecret A secret known only to the Matillion ETL and the authentication server.
AccessToken Normally used as a API Key, it allows the Matillion ETL to access the user's data; optionally access tokens can expire and refres tokens retireve a new access token.
ClientID A public identifer for the application.
Verifier To verify to access the data of the user.
OrganizationURL The URL of the OAuth API user's platform.

Server Response

    {
        {
      "name": "OAuths",
      "statusList": [
        {
          "success": true,
          "name": "ExampleOAuth"
        },
        ],
      "success": true
      }



GET/id


Summary

This permits to recover the ID related with the chosen OAuth.

Base URL

http://<instance address>/rest/v1/oauth/name/<OAuth name>/id

Server Response

{
1234567
}



GET/name


Summary

Get the name of the selected OAuth.

Base URL

http://<instance address>/rest/v1/oauth/name/<OAuth name>/name

Server Response

{
ExampleOAuth
}



GET/type


Summary

This endpoint will uncover the "service Type" of the chosen OAuth from the list. Essentially, it is the sort of the third-party "service" you've got chosen when created OAuth within the Matillion ETL.

Base URL

http://<instance address>/rest/v1/oauth/name/<OAuth name>/type

Server Response

{
<service name>
}



GET/status


Summary

This permits you to recover the status of the chosen OAuth weather "Configured" or "Not Configured".

Base URL

http://<instance address>/rest/v1/oauth/name/<OAuth name>/status

Server Response

{
Configured
}



GET/settings

This endpoint will get the settings data of the chosen OAuth. Essentially, it gives you the message, which was related with the settings property of the chosen OAuth within the Matillion ETL.

Base URL

http://<instance address>/rest/v1/oauth/name/<OAuth name>/settings

Server Response

{
"success": true,
"msg": "xyz",
"id": -1
}

POST/delete

Summary

This endpoint will delete the selected OAuth from the collection of OAuths in the Matillion ETL.

Base URL

http://<instance address>/rest/v1/oauth/name/<OAuth name>/delete

Server Response

{
"success": true,
"msg": "Successfully deleted the OAuth with the name: ExampleOAuth.",
"id": -1
}



GET/export


Summary


This endpoint will assist you to get the choosen OAuth and details from list of avalaible OAuths in the Matillion ETL.


Base URL

http://<instance address>/rest/v1/oauth/name/<OAuth name>/export

Server Response

{
"objects": [
{
"name": "<OAuthname>",
"serviceID": <ServiceID>,
"properties": {
    "CallbackURL": "<OAuth Redirect URL>",
    "AccountId": "<AccounID>",
    "RefreshToken": "<Refresh Token>",
    "ClientSecret": "<Client Secret>",
    "AccessToken": "<Access Token>",
    "ClientID": "<Client ID>",
    "DeveloperToken": "<Developer Token>",
    "CustomerId": "<Customer ID>",
    "Verifier": "<Verifier>",
    "UseSandbox": "true"
},
"files": {},
"settings": "<OAuth Settings>"
}
],
"version": "<Matillion ETL Client Version>",
"environment": "redshift"
}



DELETE


Summary

The HTTP DELETE method is used to delete a resource from the server. This will delete the selected OAuth and its details from the Matillion ETL server.

Base URL

http://<instance address>/rest/v1/oauth/name/<OAuth name>

Server Response

{
"success": true,
"msg": "Successfully deleted the OAuth with the name: ExampleOAuth_1.",
"id": 2
}