Skip to content

APIs

Jump to bottom
Shashank Huddedar edited this page Aug 7, 2023 · 6 revisions

Goscheduler provides an extensive collection of API endpoints, designed to enable comprehensive control and seamless interaction with its scheduling functionalities. For all interactions with GoScheduler's APIs, the following headers should be included:

Header-Type Value
Accept application/json
Content-Type application/json

Note: Authentication is not required.

HealthCheck

Endpoint: GET /goscheduler/healthcheck

Description: This API is used to perform a health check or status check for the server. It checks whether the service is up and running.

Curl:

curl --location --request GET 'http://localhost:8080/goscheduler/healthcheck'

Sample Success Response: 200

{
    "statusMessage": "Success"
}

Sample Error Response: 404

{
    "statusMessage": "Fail"
}

Register App

Endpoint: POST /goscheduler/apps

Description: This API handles the registration of client applications.

Request Payload:

{
  "appId": "string",
  "partitions": "integer",
  "active": "boolean"
}

Body Parameters:

  • appId: (string) The unique identifier for the application. This field cannot be empty.
  • partitions: (integer) The number of partitions. If set to zero, the default count from the service's configuration will be assigned.
  • active: (boolean) Represents the activation status of the app. If true, it represents an active app; if false, it represents a deactivated app.

Curl:

curl --location --request POST 'http://localhost:8080/goscheduler/apps' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
	"appId": "revamp",
	"partitions": 2,
        "active": true
}'

Sample Success Response: 200

{
    "status": {
        "statusCode": 201,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 1
    },
    "data": {
        "appId": "revamp",
        "partitions": 2,
        "active": true
    }
}

Sample Error Response: 400

{
    "status": {
        "statusCode": 400,
        "statusMessage": "AppId cannot be empty",
        "statusType": "Fail"
    }
}

Get Apps

Endpoint: GET /goscheduler/apps

Description: This API retrieves information about multiple apps based on the app_id query parameter. If there is no app_id present in the request, it retrieves all the apps.

Query Params:

Param Description Type of Value Sample value
app_id The ID of the app for which the schedule is created String revamp

Curl:

curl --location --request GET 'http://localhost:8080/goscheduler/apps?app_id=revamp' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Sample Success Response: 200

{
    "status": {
        "statusCode": 200,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 2
    },
    "data": {
        "apps": [
            {
                "appId": "opensource",
                "partitions": 5,
                "active": true
            },
            {
                "appId": "revamp",
                "partitions": 2,
                "active": true
            }
        ]
    }
}

Create One-time Schedule

Endpoint: POST /goscheduler/schedules

Description: This API creates a schedule based on the data provided in the request body.

Request Payload:

{
    "appId": "revamp",
    "payload": "{}",
    "scheduleTime": 2687947561,
    "callback": {
        "type": "http",
        "details": {
            "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
            "method": "GET",
            "headers": {
                "Content-Type": "application/json",
                "Accept": "application/json"
            }
        }
    }
}

Body Parameters:

  • appId: (string) The unique identifier for the application. This field cannot be empty.
  • payload: (string) The payload data for the schedule.
  • scheduleTime: (integer) The epoch time for the callback. Epoch cannot be of past time.
  • callback: (object) Contains details about the HTTP callback:
    • type: (string) The type of callback, e.g., "http".
    • details: (object) Contains the URL, method, and headers for the HTTP callback.

Curl:

curl --location --request POST 'http://localhost:8080/goscheduler/schedules' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "appId": "revamp",
    "payload": "{}",
    "scheduleTime": 2687947561,
    "callback": {
        "type": "http",
        "details": {
            "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
            "method": "GET",
            "headers": {
                "Content-Type": "application/json",
                "Accept": "application/json"
            }
        }
    }
}'

Sample Success Response: 200

{
    "status": {
        "statusCode": 201,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 1
    },
    "data": {
        "schedule": {
            "scheduleId": "1497b35c-1a21-11ee-8689-ceaebc99522c",
            "payload": "{}",
            "appId": "revamp",
            "scheduleTime": 2529772970,
            "Ttl": 0,
            "partitionId": 1,
            "scheduleGroup": 2529772920,
            "httpCallback": {
                "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
                "method": "GET",
                "headers": {
                    "Accept": "application/json",
                    "Content-Type": "application/json"
                }
            }
        }
    }
}

Sample Error Response: 400

{
    "status": {
        "statusCode": 400,
        "statusMessage": "parse \"www.myntra.com\": invalid URI for request,Invalid http callback method ,schedule time : 1629772970 is less than current time: 1688443428 for app: revamp. Time cannot be in past.",
        "statusType": "Fail"
    }
}

Create Cron-Schedule

Endpoint: POST /goscheduler/schedules

Description: The purpose of this API is to create a cron schedule based on the cron expression provided in the request body. To create a cron schedule, the Athena app must be registered.

Request Payload:

{
    "appId": "athena",
    "payload": "{}",
    "cronExpression": "*/5 * * * *",
    "callback": {
        "type": "http",
        "details": {
            "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
            "method": "GET",
            "headers": {
                "Content-Type": "application/json",
                "Accept": "application/json"
            }
        }
    }
}

Body Parameters:

  • appId: (string) The unique identifier for the application. This field cannot be empty.
  • payload: (string) The payload data for the schedule.
  • cronExpression: (string) The cron expression for scheduling. Supported cron expressions
  • callback: (object) Contains details about the HTTP callback:
    • type: (string) The type of callback, e.g., "http".
    • details: (object) Contains the URL, method, and headers for the HTTP callback.

Curl:

curl --location --request POST 'http://localhost:8080/goscheduler/schedules' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "appId": "Athena",
    "payload": "{}",
    "cronExpression": "*/5 * * * *",
    "callback": {
        "type": "http",
        "details": {
            "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
            "method": "GET",
            "headers": {
                "Content-Type": "application/json",
                "Accept": "application/json"
            }
        }
    }
}'

Sample Success Response: 200

{
    "status": {
        "statusCode": 201,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 1
    },
    "data": {
        "schedule": {
            "scheduleId": "167233ef-1fce-11ee-ba66-0242ac120004",
            "payload": "{}",
            "appId": "Athena",
            "partitionId": 0,
            "callback": {
                "type": "http",
                "details": {
                    "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
                    "method": "GET",
                    "headers": {
                        "Content-Type": "application/json",
                        "Accept": "application/json"
                    }
                }
            },
            "cronExpression": "*/6 * * * *",
            "status": "SCHEDULED"
        }
    }
}

Sample Error Response: 400

{
    "status": {
        "statusCode": 400,
        "statusMessage": "parse \"www.google.com\": invalid URI for request,Invalid http callback method ",
        "statusType": "Fail"
    }
}

Get Cron-Schedules

Endpoint: GET /goscheduler/crons/schedules?app_id=revamp

Description: This HTTP endpoint retrieves cron schedules based on the provided parameters - app_id and status. The various values of STATUS can be:

Status Description
SCHEDULED Represents the schedule is scheduled
DELETED Represents the schedule is deleted
SUCCESS Represents the schedule is successfully run
FAILURE Represents the schedule is failed
MISS Represents the schedule was not triggered

Query Params:

Param Description Type of Value Example
app_id The ID of the app for which the cron schedule is created string revamp

Curl:

curl --location --request GET 'http://localhost:8080/goscheduler/crons/schedules?app_id=revamp&status=SCHEDULED' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Sample Success Response: 200

{
  "status": {
    "statusCode": 200,
    "statusMessage": "Success",
    "statusType": "Success",
    "totalCount": 0
  },
  "data": [
    {
      "scheduleId": "167233ef-1fce-11ee-ba66-0242ac120004",
      "payload": "{}",
      "appId": "revamp",
      "partitionId": 0,
      "callback": {
        "type": "http",
        "details": {
          "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
          "method": "GET",
          "headers": {
            "Accept": "application/json",
            "Content-Type": "application/json"
          }
        }
      },
      "cronExpression": "*/6 * * * *",
      "status": "SCHEDULED"
    }
  ]
}

Sample Error Response: 404

{
    "status": {
        "statusCode": 404,
        "statusMessage": "No cron schedules found",
        "statusType": "Fail"
    }
}

Get Schedule API

Endpoint: GET /goscheduler/schedules/{scheduleId}

Description: This API retrieves a schedule by its ID, handles different retrieval scenarios, and returns the appropriate response with the retrieved schedule or error information.

Path Parameters:

  • scheduleId: (string) The unique identifier for the schedule.

Curl:

curl --location --request GET 'http://localhost:8080/goscheduler/schedules/1497b35c-1a21-11ee-8689-ceaebc99522c' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Sample Success Response: 200

{
    "status": {
        "statusCode": 200,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 1
    },
    "data": {
        "schedule": {
            "scheduleId": "1497b35c-1a21-11ee-8689-ceaebc99522c",
            "payload": "{}",
            "appId": "revamp",
            "scheduleTime": 2529772970,
            "partitionId": 1,
            "scheduleGroup": 2529772920,
            "callback": {
              "type": "http",
              "details": {
                "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
                "method": "GET",
                "headers": {
                  "Accept": "application/json",
                  "Content-Type": "application/json"
                }
              }
            },
            "status": "SCHEDULED"
        }
    }
}

Sample Error Response: 404

{
    "status": {
        "statusCode": 404,
        "statusMessage": "Schedule with id: 4588e23e-ae06-11ec-bcba-acde48001122 not found",
        "statusType": "Fail"
    }
}

Get Schedules with all runs API

Endpoint: GET /goscheduler/schedules/{scheduleId}/runs?when=future&size=1

Description: This API retrieves the runs of a schedule (execution instances) based on the schedule's ID.

Path Parameters:

  • scheduleId: (string) The unique identifier for the schedule.

Query Params:

Param Description Type of Value Example
when time-frame string past/future
size number of results we want to fetch int 1

Curl:

curl --location --request GET 'http://localhost:8080/goscheduler/schedules/1497b35c-1a21-11ee-8689-ceaebc99522c/runs?when=future&size=1' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Sample Success Response: 200

{
    "status": {
        "statusCode": 200,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 11
    },
    "data": {
        "schedules": [
            {
                "scheduleId": "26631a1b-1fd6-11ee-ba9c-0242ac120004",
                "payload": "{}",
                "appId": "revamp",
                "scheduleTime": 1689071760,
                "partitionId": 0,
                "scheduleGroup": 1689071760,
                "callback": {
                    "type": "http",
                    "details": {
                        "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
                        "method": "GET",
                        "headers": {
                            "Accept": "application/json",
                            "Content-Type": "application/json"
                        }
                    }
                },
                "status": "SCHEDULED"
            },
            {
                "scheduleId": "4fda1178-1fd5-11ee-ba96-0242ac120004",
                "payload": "{}",
                "appId": "revamp",
                "scheduleTime": 1689071400,
                "partitionId": 0,
                "scheduleGroup": 1689071400,
                "callback": {
                    "type": "http",
                    "details": {
                        "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
                        "method": "GET",
                        "headers": {
                            "Accept": "application/json",
                            "Content-Type": "application/json"
                        }
                    }
                },
                "status": "FAILURE",
                "errorMessage": "404 Not Found"
            },
          {
            "scheduleId": "2c0df520-1fce-11ee-ba68-0242ac120004",
            "payload": "{}",
            "appId": "revamp",
            "scheduleTime": 1689068160,
            "partitionId": 0,
            "scheduleGroup": 1689068160,
            "callback": {
              "type": "http",
              "details": {
                "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
                "method": "GET",
                "headers": {
                  "Accept": "application/json",
                  "Content-Type": "application/json"
                }
              }
            },
            "status": "MISS",
            "errorMessage": "Failed to make a callback"
          }
        ],
      "continuationToken": ""
    }
}

Sample Error Response: 404

{
    "status": {
        "statusCode": 404,
        "statusMessage": "No runs found for schedule with id 1305aec5-e233-11ea-97ed-000d3af279cb",
        "statusType": "Fail"
    }
}

9. Get Paginated Schedules by appId API

This API get all the schedules associated with a specific application ID based on time range and status in a paginated way.

It throws an error if the application Id is not registered, or if the application details are not fetched successfully.

It handles different scenarios based on the parsed query parameters:

  1. If there is an error parsing the query parameters, it handles the invalid data error and returns an appropriate response.
  2. If the size parameter is less than 0, it handles the invalid data error.
  3. If the endTime of the timeRange is before the startTime, it handles the invalid data error.
  4. If the time range is greater than a predefined number of days (30 days in this case), it handles the invalid data error and returns an appropriate response.
  5. If the query parameters are successfully parsed, the function calls the GetPaginatedSchedules method of the scheduleDao to retrieve paginated schedules based on the application ID and other parameters.

Method: GET

http://localhost:8080/goscheduler/apps/revamp/schedules

Query Params

Param Description Type of Value Example
size number of results we want to fetch int 5
start_time start time of the range to fetch all schedules string 2023-06-28 10:00:00
end_time end time of the range to fetch all schedules string 2023-07-02 12:00:00
continuationToken token to fetch the next set of schedules string 19000474657374000004000000
continuationStartTime startTime from where we continue fetching next set of schedules long 1687930200
status status type of the schedules we want to fetch string ERROR

Note : ContinuationToken and continuationStartTime are generated after the first call, it's not needed for the first time api call.

Curl

curl --location --request GET 'http://localhost:8080/goscheduler/apps/revamp/schedules?size=5&start_time=2023-06-28 10:00:00&status=SUCCESS&end_time=2023-07-02 12:00:00' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Sample Success Response: 200

{
    "status": {
        "statusCode": 200,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 2
    },
    "data": {
        "schedules": [
            {
                "scheduleId": "d5e0fd64-26bc-11ee-8f1a-aa665a372253",
                "payload": "{}",
                "appId": "test",
                "scheduleTime": 1689830381,
                "partitionId": 0,
                "scheduleGroup": 1689830340,
                "callback": {
                    "type": "http",
                    "details": {
                        "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
                        "method": "GET",
                        "headers": {
                            "Accept": "application/json",
                            "Content-Type": "application/json"
                        }
                    }
                },
                "status": "SUCCESS"
            },
            {
                "scheduleId": "cf8e385a-26bc-11ee-8f15-aa665a372253",
                "payload": "{}",
                "appId": "test",
                "scheduleTime": 1689830381,
                "partitionId": 0,
                "scheduleGroup": 1689830340,
                "callback": {
                    "type": "http",
                    "details": {
                        "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
                        "method": "GET",
                        "headers": {
                            "Accept": "application/json",
                            "Content-Type": "application/json"
                        }
                    }
                },
                "status": "SUCCESS"
            }
        ],
        "continuationToken": "19000474657374000004000000000000080000018971bcb5a000120010cf8e385a26bc11ee8f15aa665a372253f07ffffffdf07ffffffd",
        "continuationStartTime": 1689827400
    }
}

Sample Error Response: 400

{
    "status": {
        "statusCode": 400,
        "statusMessage": "Time range of more than 30 days is not allowed",
        "statusType": "Fail"
    }
}

10. Deactivate App API

This API handles the deactivation of an application by updating its active status to "false" in the database, deactivating the application in the supervisor, and returning an appropriate response indicating the deactivation status. On deactivation, all the pollers will be stopped, so no new schedules could be created and no schedules will be triggered.

Method: POST

http://localhost:8080/goscheduler/apps/revamp/deactivate

Curl

curl --location --request POST 'http://localhost:8080/goscheduler/apps/revamp/deactivate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Sample Success Response: 200

{
    "status": {
        "statusCode": 201,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 0
    },
    "data": {
        "appId": "revamp",
        "Active": false
    }
}

Sample Error Resonse: 400

{
    "status": {
        "statusCode": 4001,
        "statusMessage": "unregistered App",
        "statusType": "Fail"
    }
}

11. Activate App API

This API handles the activation of an application by updating its active status in the database, activating the application in the supervisor, and returning an appropriate response indicating the activation status.

It checks if the Active field of the application is already set to true. If it is true, it records the activation failure and returns an appropriate response indicating that the app is already activated.

Method: POST

http://localhost:8080/goscheduler/apps/revamp/activate

Curl

curl --location --request POST 'http://localhost:8080/goscheduler/apps/revamp/activate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Sample Success Response: 200

{
    "status": {
        "statusCode": 201,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 0
    },
    "data": {
        "appId": "revamp",
        "Active": true
    }
}

Sample Error Response: 4XX

{
    "status": {
        "statusCode": 4001,
        "statusMessage": "unregistered App",
        "statusType": "Fail"
    }
}
{
    "status": {
        "statusCode": 4003,
        "statusMessage": "app is already activated",
        "statusType": "Fail"
    }
}

12. Reconcile/Bulk Action API

This API gets all the schedules of an app in bulk based on time range and status.

This HTTP endpoint that handles bulk actions for schedules of an app based on status.

Based on actionType, it performs the following actions:

  • If it is reconcile, it retriggers all the schedules of an app again. If it is Delete, it deletes all the schedules of the app in bulk.
  • If the actionType is invalid, handle the error and return an appropriate response indicating the invalid action type.

It parses the request to extract the time range and status parameters. The end time of the time range should be before the start time and the duration of the time range should not exceed the maximum allowed period.

Method: POST

http://localhost:8080/goscheduler/apps/revamp/bulk-action/reconcile?status=SUCCESS&start_time=2023-02-06%2010:47:00&end_time=2023-02-06%2011:50:00

Query Params

Param Description Type of Value Example
status status type of the schedules we want to fetch string SUCCESS
start_time start time of the range to fetch all schedules string 2023-02-06 10:47:00
end_time end time of the range to fetch all schedules string 2023-02-06 11:50:00

Curl

curl --location --request POST 'http://localhost:8080/goscheduler/apps/revamp/bulk-action/reconcile?status=SUCCESS&start_time=2023-02-06%2010:47:00&end_time=2023-02-06%2011:50:00' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Sample Success Response : 200

{
    "status": {
        "statusCode": 200,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 0
    },
    "remarks": "reconcile initiated successfully for app: revamp, timeRange: {StartTime:2023-02-06 10:47:00 +0530 IST EndTime:2023-02-06 11:50:00 +0530 IST}, status: SUCCESS"
}

13. Delete Schedule API

This API cancels a schedule based on its ID, handles different deletion scenarios, and returns the appropriate response with the deleted schedule or error information. On deleting a cron schedule, all the children runs will also be deleted.

After a particular schedule is deleted, if we run this delete schedule API again, it would give "Not found".

Method: DELETE

http://localhost:8080/goscheduler/schedules/1497b35c-1a21-11ee-8689-ceaebc99522c

Curl

curl --location --request DELETE 'http://localhost:8080/goscheduler/schedules/1497b35c-1a21-11ee-8689-ceaebc99522c' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Sample Success Response: 200

{
    "status": {
        "statusCode": 200,
        "statusMessage": "Success",
        "statusType": "Success",
        "totalCount": 1
    },
    "data": {
        "schedule": {
            "scheduleId": "1497b35c-1a21-11ee-8689-ceaebc99522c",
            "payload": "{}",
            "appId": "revamp",
            "scheduleTime": 2529772970,
            "Ttl": 0,
            "partitionId": 1,
            "scheduleGroup": 2529772920,
            "httpCallback": {
                "url": "http://127.0.0.1:8080/goscheduler/healthcheck",
                "method": "GET",
                "headers": {
                    "Accept": "application/json",
                    "Content-Type": "application/json"
                }
            }
        }
    }
}

Sample Error Response: 404

{
    "status": {
        "statusCode": 404,
        "statusMessage": "not found",
        "statusType": "Fail"
    }
}
Clone this wiki locally