API v1 - Git Integration

API v1 - Git Integration


Overview

This is a guide to providing details on the SCM API, also can be referred as GIT Integration services offered by Matillion ETL. SCM (Source Control Management) API is a part of the "Version API" family endpoint.

The Matillion ETL uses GIT for its version control, allowing teams to track a project's changes (both small and large) with speed and efficiency.

Important Information

  • This document is part of a series on SCM Integration , GIT Integration and Matillion ETL API - v1.
  • This process requires the Matillion ETL instance URL, the username and password of a user with appropraite permissions.
  • 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.

SCM API Endpoints

API Base URL

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

API Endpoints and Function

SCM API is available on standard REST-based APIs that uses HTTP or HTTPS request to GET and POST data. The SCM 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 URI Function
GET /differences http://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/scm/difference Returns the difference between the current version (including uncommitted changes) and the head.
POST /init http://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/scm/init Initialise a new repository in this version.
POST /clone http://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/scm/clone Clone an existing repository.
POST /switchCommit http://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/scm/switchCommit Switch to an existing commit by passing the commit ID.



Graphical Represenation

To illustrate the SCM API, endpoints and methods to the further, below is the graphical flow of the /scm endpoint showing possible PATH, GET , POST, and DELETE options.

SCM API Endpoint Flow

SCM API Endpoint Flow



URL 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.
<groupName> the name of the group.
<projectName> The name of the project within the group.
<versionName> The name of the version within the selected project.
<init> initializing a new repository.
<clone> Clone an existing repository.
<difference> Returns the difference between the current version (including uncommitted changes) and the head.
<switchCommit> Switch to another GIT commit.



Endpoints and Server Response

This chapter describes the SCM 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 the GIT integration within the Matillion instance.

All the APIs listed in this chapter are available to use with GET/POST/DELETE HTTP methods .

GET/differences

To get differences between the current Matillion version and the branch head, make the following GET call:

Base URL
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>scm/differences
Endpoint

Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Get differences endpoint


POST/init

To initialise a local repo using the Matillion v1 API, make the following POST call:

Base URL

<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/scm/init

Here is an example of this request with variables added (the instance address has not been added):

{host:port}/rest/v1/group/name/Docs_Project/project/name/Docs/version/name/default/scm/init

The variables in the above example are listed immediately below for added clarity. For security reasons, the instance address remains hidden.

  • groupName = Docs_Project
  • projectName = Docs
  • versionName = default

Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Init local repo endpoint

The table below documents the type of API endpoint, the body (in a JSON format), a description of the endpoint, and any pertinent notes that users should consider.

Method Body (JSON) Description
POST
{
"commitMessage": "<Your Commit Message>",
"userIdentifier": {
"username": "<username>",
"emailAddress": "<emailaddress>"
}
}
Initialises a new repository in this Matillion ETL version.

This request creates an initial Git commit within Matillion ETL.
 
  • commitMessage: A message to include with your commit. This will be visible on the commit inside the Matillion ETL client
  • username: The username to attach to the commit. Note this is not necessarily your username for the remote repository nor your Matillion ETL instance username and does not affect anything else.
  • emailAddress: The email address to attach to the commit (xxx@xxx.xxx). Note this is not necessarily your email for the remote repository nor your Matillion ETL instance email and does not affect anything else.

POST/clone

To clone a remote repository, make the following POST call:

Base URL
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/scm/clone

Here is an example of this request with variables added (the instance address has not been added):

{host:port}/rest/v1/group/name/Docs_Proj/project/name/Docs/version/name/default/scm/clone

Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Clone remote repo endpoint

The table below documents the type of API endpoint, the body (in a JSON format), a description of the endpoint, and any pertinent notes that users should consider.

Method Body (JSON) Description
POST
{
"remoteURI":"<URL>",
"auth": {
"authType": "HTTPS",
"username": "<username>",
"password": "<password>"
}
}
Clone an existing remote repository in this Matillion ETL version.

Successful requests will initialise from or clone your remote repository.
 
  • remoteURI: The URL of your remote Git repository
  • authType: Matillion ETL currently supports "HTTPS" only
  • username: The username to authenticate with the remote repository
  • password: The corresponding password for the above username

POST/switchCommit

To switch to another Git commit using the API, make the following POST call:

Base URL
<instanceaddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/version/name/<versionName>/scm/switchCommit

Here is an example of this request with variables added (the instance address has not been added):

{host:port}/rest/v1/group/name/Docs_Proj/project/name/Docs/version/name/default/scm/switchCommit

Here is the endpoint as seen when running the {host:port}/rest/v1 in a browser:

Switch commit endpoint

The table below documents the type of API endpoint, the body (in a JSON format), and a description of the endpoint.

Method Body (JSON) Description
POST
{
"commitID": "<ID>"
}
Switch to an existing commit by passing the commit ID. You can find commit IDs by using the 'getState' endpoint detailed in the 'Get Commits' section of this article.
 
  • commitID: The commit ID of the commit to switch to