API v1 - OAuth

Overview

This is a guide to providing details on the OAuth API services offered by Matillion ETL instance. OAuth API services allows data to be imported from the service providers such as Facebook, Salesforce, Hubspot, BingAds and 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.

OAuth API Endpoints

API Base URL

http(s)://<InstanceAddress>/rest/v1/<oauth>

API Endpoints and Function

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:

Graphical Representation

To illustrate the OAuth API, endpoints to the further, below is the graphical flow of the /oauth endpoint showing possible methods GET, POST, and DELETE .

API Parameters and Description

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

Endpoints and Server Response

This chapter describes the OAuth API endpoints along with some examples from the server response. 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 HTTP methods .

List of endpoints for the /oauth:

• GET/properties
• GET/id
• GET/name
• GET/type
• GET/status
• GET/settings
• GET/export
• POST/import
• POST/delete
• DELETE/oauthName

Below is the detailed description of these endpoints with example response from the server.

GET/properties

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://<InstanceAddress>/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>"
  }

GET/id

This endpoint request is to get the ID of the chosen OAuth with the GET HTTP method.

• Base URL

  http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/id

• Server Response

  {
  123456
  }
  

GET/name

This is a Get request to fetch the name of the selected OAuth.

• Base URL

  http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/name

• Server Response

  {
  ExampleOAuth
  }
  

GET/type

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://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/type

• Server Response

  {
  <service name>
  }
  

GET/status

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

• Base URL

  http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/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://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/settings

• Server Response

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

GET/export

To export the selected OAuth detail available within the Matillion instance, provide the oauthName and use the /export endpoint. This example using GET method REST API call to export the OAuth details .

• Base URL

  http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/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"
  }

POST/import

Now you have already exported the OAuth details in the example before using GET/export endpoint that includes OAuth name, serviceID and other properties. Please note, the "serviceID" is the unique identifier assigned to the OAuth by server and you will need this value in the POST body of /import endpoint. POST/import endpoint is to import OAuth details which you have already retrieved from the GET/export endpoint. This will be a POST method API call as we will have to attach the variable for the OAuth to be imported, in the body as a JSON file to run into the Matillion ETL instance.

• Base URL

  http://<InstanceAddress>/rest/v1/oauth/import

• POST Body(JSON)

  {
  "objects": [
  {
  "name": "OAuthImported",
  "serviceID": <serviceID>,
  "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	Data type	Description
name	String	The name of the OAuth you wanted to add into the Matillion ETL.
serviceID	Number	Unique identifier assigned to the OAuth. This value you can retrieve using GET/export endpoint as mentioned in the example.
CallbackURL	String	Callback URL that used to send and receive the data invokes after the authentication process with Matillion ETL.
RefreshToken	String	Token used to obtain a renewed Access Token.
ClientSecret	String	A secret known only to Matillion ETL and the authentication server.
AccessToken	String	Normally used as an API Key, it allows Matillion ETL to access the user's data. Optionally, access tokens can expire and refers tokens retrieve a new access token.
ClientID	String	A public identifier for the application.
Verifier	String	To verify to access the data of the user.
OrganizationURL	String	The URL of the OAuth API user's platform.

• Server Response

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

POST/delete

This endpoint will delete the selected OAuth from the collection of OAuths in the Matillion ETL using POST HTTP method.

• Base URL

  http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/delete

• Server Response

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

DELETE/oauthName

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://<InstanceAddress>/rest/v1/oauth/name/<oauthName>

• Server Response

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