API v1 - Schedules

API v1 - Schedules


Overview

This is a guide to providing details on the Schedule API from the familiy of the Group API . The Schedule endpoint allows users to explore the "resource" details to run the job within the Project Group in the Matillion ETL instance. By "resources" here, we refer to retrieve schedule metadata such as; name, DayOfweek, timing to run the job, version name, environment name, and job name, other resources are; get id, update, export/import and delete job schedules within Projects and Groups in which they reside.

Important Information

  • This document is part of a series on API v1 - Group and the Matillion ETL API - v1.
  • 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.
  • 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.

Schedule API Endpoints

API Base URL

http(s)://<InstanceAddress>/rest/v1/group/name/<groupName>/project/name/<projectName>/schedule

API Endpoints and Function

Schedule endpoint API is available on standard REST-based APIs that uses HTTP or HTTPS request to GET, POST, and DELETE data. The Schedule endpoint API service is accessed through the Uniform Resource Identifier (URI). All following references in this document will assume the API Base URL. The available API endpoints are listed below:

Method Path URI Function
GET /name http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/name Get the name of the selected schedule within the group.
GET /id http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/id Get the Queue Id of the schedule.
GET /export http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/export Produces an export container containing this schedule.
POST /delete http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/delete Delete the selected schedule via a HTTP POST request.
POST /update http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/update?ignoreUnresolved=false WITH POST DATA arg1 Update the selected schedule within the project.
DELETE /scheduleName http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName> Delete the selected schedule via a HTTP DELETE request.

Graphical Represenation

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

Schedule endpoint Flow

Schedule 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.
<name> To get the name of the resource.
<update> This allows to update the selected resource.
<delete> Delete the selected resource.
<id> The queue id of the resource.



Endpoints and Server Response

This chapter describes the Schedule API endpoints with some server response examples. These APIs offers REST-based web service, offering ease of use and a flexible choice of programming language.

All the APIs listed in this chapter are available to use with GET/POST/DELETE methods to retrieve the data used to get, update, or delete the schedule.

List of endpoints for the /schedule:

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

GET/name

This example is a GET method REST API request that will provide the name of the schedule created for the job to run within the project in the instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/name
  • Server Response
    Example-Schedule

GET/id

This is to get the queue id for the selected schedule within the project.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/id
  • Server Response
    123

GET/export

To export the selected schedule from the project within the Matillion instance, provide the scheduleName and use the /export endpoint. This example using GET method REST API call to export the selected schedule and all associated information alligned with the group.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/export
  • Server Response
    {
        "objects": [
            {
                "name": "Example-Schedule",
                "minute": "30",
                "hour": "12",
                "dayOfWeek": true,
                "monday": true,
                "tuesday": false,
                "wednesday": false,
                "thursday": false,
                "friday": false,
                "saturday": false,
                "sunday": false,
                "daysOfMonth": "",
                "enabled": true,
                "timezone": "Europe/London",
                "versionName": "default",
                "jobName": "dim_airport_setup",
                "environmentName": "test",
                "preventDuplicateJob": false
            }
        ],
        "version": "master",
        "environment": "redshift"
    }

POST/delete

This will be a POST method API call. The /delete endpoint will allow to delete the selected schedule from the project.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/delete
  • Server Response
    {
      "success": true,
      "msg": "Successfully deleted the schedule: Example-Schedule",
      "id": -1
    }

POST/update

The /update endpoint will allow to update the selected schedule. This will be a POST method API call as we will have to attach the project, in the body as a JSON file to import into the Matillion ETL instance.

Please Note

Make sure, if the resource of the same name already exists, you must delete the existing resource before importing the new or should change the name of the project to be imported in the POST Body.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>/update?ignoreUnresolved=false WITH POST DATA arg1
  • POST BODY(JSON)
    {
                "name": "Schedule-Imported01",
                "minute": "30",
                "hour": "08:00",
                "dayOfWeek": true,
                "monday": true,
                "enabled": true,
                "timezone": "UTC",
                "versionName": "default",
                "jobName": "dim_airport_setup",
                "environmentName": "test",
                "preventDuplicateJob": true
    }

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

    Field Name Description
    name The name of the schedule.
    minute Time of execution for the job in minutes.
    Hours Time of execution for the job in hours. For example: 4:15pm would be 16 hours and 15 minutes.
    DayofWeek Jobs can be scheduled to run on a weekly basis or indeed each day if all days are selected in Days Of Week. Select any day from week and enter the value as "true".
    TimeZone Provide the time zone, you would like to schedule the job . The job itself is run by Matillion ETL, which is always based on UTC and is offset to local time using the Timezone you select and put the value for.
    Version Provide the version of the project you wish to run at the scheduled time.
    Job Select the Orchestration job you wish to run at the scheduled time.
    Environment Select the environment you wish to run against at the scheduled time.
    preventDuplicateJob Allows users to specify that a scheduled job run should not queued if that same job from a previous schedule is still running, preventing duplicates from stacking up in the queue.
  • Server Response
    {
      "success": true,
      "msg": "Successfully updated schedule [Schedule-Imported01]",
      "id": 0
    }

DELETE/scheduleName

To remove any resource from the list, we will use DELETE API request. In this example, we will delete a schedule created to run a job in the Matillion ETL instance.

  • Base URL
    http://<InstanceAddress>/rest/v1/group/name/<groupname>/project/name/<projectName>/schedule/name/<scheduleName>
  • Server Response
    {
      "success": true,
      "msg": "Successfully deleted schedule [Example-Schedule]",
      "id": -1
    }

Please Note

There are often multiple ways of achieving the same task within the API as resources and methods branch out and overlap.