API v1 - Group

API v1 - Group


The Group endpoint allows users to explore the resources in their Matillion ETL instance. By resources here, we refer to Jobs and the Versions, Projects and Groups in which they reside. This also ties into various services such as Schedules, which too are available through this endpoint. As such, Group is one of the largest and most diverse endpoints in the Matillion v1 API. Below we provide a basic outline of this endpoint followed by a series of API examples that accomplish common tasks that can be used (almost) as-is or used to help construct more bespoke API calls.

The goal here is to provide a bitesized, independent, generic example of the GET and POST options found in the Group endpoint of the v1 API. 

Note: Matillion ETL Tasks can be accessed via the Group endpoint. For examples of this, see API v1 - Tasks.
 

Finding Resources


The v1 API can be used to list the names of resources that can then be used to access those resources.

Finding Groups
curl -X GET -u api-user:password https://<InstanceAddress>/rest/v1/group/

​Accessing a specific Group by name:

curl -X GET -o mtln_grp.json -u api-user:password https://<InstanceAddress>/rest/v1/group/name/<GroupName>



Finding Projects within a Group

curl -X GET -u api-user:password https://<InstanceAddress>/rest/v1/group/name/<GroupName/project

​Accessing a specific Project by name:

curl -X GET -u api-user:password https://<InstanceAddress>/rest/v1/group/name/<GroupName>/project/name/<ProjectName>



Finding Versions within a Project

curl -X GET -u api-user:password https://<InstanceAddress>/rest/v1/group/name/<GroupName>/project/name/<ProjectName>/version

​Accessing a specific Version name:

curl -X GET -u api-user:password https://<InstanceAddress>/rest/v1/group/name/<GroupName>/project/name/<ProjectName>/version/name/<VersionName>



Finding Jobs within a Version

curl -X GET -u api-user:password https://<InstanceAddress>/rest/v1/group/name/<GroupName>/project/name/<ProjectName>/version/name/<VersionName>/job

​Accessing a specific Job by name:

curl -X GET -u api-user:password https://<InstanceAddress>/rest/v1/group/name/<GroupName>/project/name/<ProjectName>/version/name/<VersionName>/job/name/<JobName>

Import/Export all Groups

 

Export all Project Groups

curl -X GET -o mtln_grp.json -u api-user:password https://<InstanceAddress>/rest/v1/group/export


Import all Project Groups

curl -X POST -u api-user:password "https://<InstanceAddress>/rest/v1/group/import" -H "Content-Type: application/json" --data-binary @mtln_grp.json


 

Import/Export Specific Resources



Export a Specifc (Single) Project Groups

curl -X GET -o mtln_project_grp.json -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Production%<InstanceAddress>/export"


Import a Specific (Single) Project Groups

curl -X POST -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/import" -H "Content-Type: application/json" --data-binary @mtln_project_grp.json


Export a specific (single) Project

curl -X GET -o mtln_project.json -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Production%<InstanceAddress>/project/name/Laura%20Video/export"


Import a specific (single) Project

curl -X POST -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Production%<InstanceAddress>/project/import" -H "Content-Type: application/json" --data-binary @mtln_project.json


Export a specific (single) Version

curl -X GET -o mtln_project_version.json -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Demonstration%<InstanceAddress>/project/name/Kalyan%20Arangam/version/name/version1/export"


Import a specific (single) Version

curl -X POST -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Production%<InstanceAddress>/project/name/My%20Project/version/import" -H "Content-Type: application/json" --data-binary @mtln_project_version.json

Export a specific (single) Job

curl -X GET -o mtln_job_defn.json -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Demonstration%<InstanceAddress>/project/name/Kalyan%20Arangam/version/name/default/job/name/dim_airport_setup/export"


Import a specific (single) Job

curl -X POST -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Production%<InstanceAddress>/project/name/My%20Project/version/default/import" -H "Content-Type: application/json" --data-binary @mtln_job_defn.json


Import a specific (single) schedule

curl -X GET -o mtln_project_myschedule.json -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Demonstration%<InstanceAddress>/project/name/Kalyan%20Arangam/schedule/name/My%20Schedule/export"


Export a specific (single) schedule

curl -X POST -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Demonstration%<InstanceAddress>/project/name/Kalyan%20Arangam/schedule/name/My%20Schedule/export" --data-binary @mtln_project_myschedule.json


Export All Jobs (From a Version)

curl  -o dim_airport_setup.json -X GET -u api-user:password --insecure "https://<ServerIP>/rest/v1/group/name/MY_GROUP/project/name/MY_PROJECT/version/name/default/job/export"


Import Multiple Jobs

curl -X POST -u api-user:password  --insecure "https://<ServerIP>/rest/v1/group/name/MY_GROUP/project/name/MY_PROJECT/version/name/v1/job/import" -H "Content-Type: application/json" --data-binary @dim_airport_setup.json



Export A Specific (Single) Job

curl  -o dim_airport_setup.json -X GET -u api-user:password --insecure "https://<ServerIP>/rest/v1/group/name/MY_GROUP/project/name/MY_PROJECT/version/name/default/job/name/dim_airport_setup/export"


Import A Specific (Single) Job

curl -X POST -u api-user:password  --insecure "https://<ServerIP>/rest/v1/group/name/MY_GROUP/project/name/MY_PROJECT/version/name/v1/job/name/dim_airport_setup/delete"

Import/Export Schedules



Export All Schedules

curl -X GET -o mtln_project_schedules.json -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Demonstration%<InstanceAddress>/project/name/Kalyan%20Arangam/schedule/export"


Import All Schedules

curl -X POST -u api-user:api-user "https://<InstanceAddress>/rest/v1/group/name/Demonstration%<InstanceAddress>/project/name/Kalyan%20Arangam/schedule/import" -H "Content-Type: application/json" --data-binary @mtln_project_schedules.json

Deleting resources


Resources can be deleted by accessing the resource via the API then appending the /delete endpoint. For example, deleting a Project:

curl -X POST -u api-user:password "https://<InstanceAddress>/rest/v1/group/name/MY_GROUP/project/name/MY_PROJECT/delete"

Example: Promoting a Job


 Promoting a job from one version to another (for example, from Test to Live) is a common task. To accomplish this, the job (in this example, 'dim_airport_setup') to be promoted must first be exported:

curl -o dim_airport_setup.json -X GET -u api-user:password --insecure "https://<InstanceAddress>/rest/v1/group/name/MY_GROUP/project/name/MY_PROJECT/version/name/Test/job/name/dim_airport_setup/export"


Now the job an be imported to the new Version:

curl -X POST -u api-user:password  --insecure "https://<ServerIP>/rest/v1/group/name/MY_GROUP/project/name/MY_PROJECT/version/name/Live/job/import" -H "Content-Type: application/json" --data-binary @dim_airport_setup.json


And finally the old Job can be deleted:

curl -X POST -u api-user:password  --insecure "https://<ServerIP>/rest/v1/group/name/MY_GROUP/project/name/MY_PROJECT/version/name/Test/job/name/dim_airport_setup/delete"