API v1 - OAuth

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.

Important Information

  • 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.
  • For more information about accessing the Matillion API, and general information on the Matillion API platform before using the API, please refer to Matillion ETL API - v1.
  • 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.
  • 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.

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:

Method Path URL Function
GET /properties http://<InstanceAddress>/rest/v1/oauth/name/<oauthname>/properties Get the properties of the selected OAuth.
GET /id http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/id Get the ID of the selected OAuth.
GET /name http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/name Get the name of the selected OAuth.
GET /type http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/type Get the type of the selected OAuth.
GET /status http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/status Get the status of the selected OAuth.
GET /settings http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/settings Get the settings of the selected OAuth.
GET /export http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/export Export the current OAuth.
POST /import http://<InstanceAddress>/rest/v1/oauth/import Import one or more OAuths.
POST /delete http://<InstanceAddress>/rest/v1/oauth/name/<oauthName>/delete Delete the selected OAuth.
DELETE /oauthName http://<InstanceAddress>/rest/v1/oauth/name/<oauthName> Delete the selected OAuth from the server.

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 .

OAuth API endpoint Flow

OAuth API endpoint Flow



API Parameters and Description

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

Parameters Name Description
<InstanceAddress> This is the server IP address or domain name.
<oauthName> The name of the OAuth, you have created in Matillion ETL instance, using Manage OAuth. Alternatively, you can find the list of OAuths in the Matillion ETL instance by running an API call: http://<InstanceAddress>/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 resource and details to the another instance.
<id> To get the id associated with the resource.
<name> Provide the name of the selected resource.
<type> Provides the type of the selected resource.
<status> Get the status of the selected OAuth. "Configured" or "Not Configured".
<settings> To get the settings message of the selected resource.
<delete> To delete the selected resource via POST HTTP method.
<export> Export the selected resource from one instance to another.

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:

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 export the OAuth in the example before. This time is to import OAuth details within the Matillion ETL instance. 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.

Please Note

If a resource of the same name already exists, you must delete the existing resource before importing the new or you can change the name of the imported resource (OAuthImported) in the POST body.

  • Base URL
    http://<InstanceAddress>/rest/v1/oauth/import
  • POST Body(JSON)
    {
        "objects": [
            {
                "name": "OAuthImported",
               "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": "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
    }