Skip to content

APIs

Jump to bottom
Shashank Huddedar edited this page Aug 8, 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"
    }
}

Get Paginated Schedules by appId API

Endpoint: GET /goscheduler/apps/{appId}/schedules

Description: This API retrieves all the schedules associated with a specific application ID based on time range and status in a paginated way. It handles various scenarios, including error parsing, invalid data, and time range constraints, and returns the appropriate response with the retrieved schedules or error information.

Path Parameters:

  • appId: (string) The unique identifier for the application.

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; they are 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"
    }
}

Deactivate App API

Endpoint: POST /goscheduler/apps/{appId}/deactivate

Description: This API handles the deactivation of an application by updating its active status to false in the apps table. On deactivation, all the pollers will be stopped, so no new schedules could be created and no schedules will be triggered.

Path Parameters:

  • appId: (string) The unique identifier for the application.

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 Response: 400

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

Activate App API

Endpoint: POST /goscheduler/apps/{appId}/activate

Description: This API handles the activation of an application by updating its active status in the database. 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.

Path Parameters:

  • appId: (string) The unique identifier for the application.

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: 400

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

Sample Error Response: 400

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

Reconcile/Bulk Action API

Endpoint: POST /goscheduler/apps/{appId}/bulk-action/{actionType}

Description: This API gets all the schedules of an app in bulk based on time range and status. It handles bulk actions for schedules of an app based on status. Depending on the actionType, it performs specific actions:

  • If actionType is reconcile, it retriggers all the schedules of an app again.
  • If actionType is Delete, it deletes all the schedules of the app in bulk.
  • If the actionType is invalid, it handles the error and returns an appropriate response indicating the invalid action type. 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.

Path Parameters:

  • appId: (string) The unique identifier for the application.
  • actionType: (string) The type of action to perform (reconcile or Delete).

Query Parameters:

  • status: (string) Status type of the schedules to fetch (e.g., SUCCESS).
  • start_time: (string) Start time of the range to fetch all schedules (e.g., 2023-02-06 10:47:00).
  • end_time: (string) End time of the range to fetch all schedules (e.g., 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"
}

Delete Schedule API

Endpoint: DELETE /goscheduler/schedules/{scheduleId}

Description: This API cancels a schedule based on its ID, handling different deletion scenarios. On deleting a cron schedule, all the children future runs will also be deleted along with the recurring schedule. If a particular schedule is deleted it will return Not found.

Path Parameters:

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

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