API Details

The Scheduler provides REST like API with JSON payloads.

The root URL for all of the endpoints is:

https://<scheduler-domain>/api/

Authenticating to the API

Please see the Authentication and Authorization document.

Endpoints

The endpoints provided by the Seed Scheduler are split into two categories, core endpoints and helper endpoints

Core

The root URL for all of the core endpoints includes the version prefix (https://<scheduler-domain>/api/v1/)

POST /user/token/

Creates a user and token for the given email address.

If a user already exists for the given email address, the existing user account is used to generate a new token.

Request JSON Object:
 
  • email (string) – the email address of the user to create or use.
Response JSON Object:
 
  • token (string) – the auth token generated for the given user.
Status Codes:

Example request:

POST /user/token/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

{
    "email": "bob@example.org"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "token": "c05fbab6d5f912429052830c77eeb022249324cb"
}

Users and Groups

GET /user/

Returns a list of users for the Seed Scheduler service.

Status Codes:

Example request:

GET /user/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "john@example.org",
            "groups": [],
            "url": "http://scheduler.example.org/api/v1/user/1/",
            "username": "john"
        }
    ]
}
GET /user/(int: user_id)/

Returns the details of the specified user ID.

Parameters:
  • user_id (int) – a user’s unique ID.
Status Codes:

Example request:

GET /user/1/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "email": "john@example.org",
    "groups": [],
    "url": "http://scheduler.example.org/api/v1/user/1/",
    "username": "john"
}
GET /group/

Returns a list of groups for the Seed Scheduler service.

Status Codes:

Example request:

GET /group/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "name": "Admins",
            "url": "http://scheduler.example.org/api/v1/group/1/"
        }
    ]
}
GET /group/(int: group_id)/

Returns the details of the specified group ID.

Parameters:
  • group_id (int) – a group’s unique ID.
Status Codes:

Example request:

GET /group/1/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "Admins",
    "url": "http://scheduler.example.org/api/v1/group/1/"
}

Schedules

GET /schedule/

Returns a list of Schedules.

POST /schedule/

Creates a new Schedule.

Request JSON Object:
 
  • frequency (int) – (Deprecated) an optional integer number of times a task should be run in total.
  • endpoint (string) – a URL to POST to when this schedule is run.
  • cron_definition (string) – A crontab definition of when to run this schedule.
  • inteval_definition (string) – An interval definition of when to run this schedule.
  • auth_token (string) – An auth token to use when POSTing to the endpoint.
  • payload (json) – The JSON payload to include when POSTing to the endpoint.
  • enabled (boolean) – A boolean flag of whether this schedule is enabled.
Response Headers:
 
  • Location – the URL to the newly created resource.
Status Codes:
GET /schedule/(uuid: schedule_id)/

Retuns the Schedule record for a given schedule_id.

PUT /schedule/(uuid: schedule_id)/

Updates the Schedule record for a given schedule_id.

Request JSON Object:
 
  • frequency (int) – an optional integer number of times a task should be run in total.
  • endpoint (string) – a URL to POST to when this schedule is run.
  • cron_definition (string) – A crontab definition of when to run this schedule.
  • inteval_definition (string) – An interval definition of when to run this schedule.
  • auth_token (string) – An auth token to use when POSTing to the endpoint.
  • payload (json) – The JSON payload to include when POSTing to the endpoint.
  • enabled (boolean) – A boolean flag of whether this schedule is enabled.
Status Codes:
DELETE /schedule/(uuid: schedule_id)/

Deletes the Schedule record for a given schedule_id.

Helpers

The root URL for the helper endpoints does not include a version prefix (https://<scheduler-domain>/api/)

GET /metrics/

Returns a list of all the available metric keys provided by this service.

Status Codes:
POST /metrics/

Starts a task that fires all scheduled metrics.

Status Codes:
GET /health/

Returns a basic health check status.

Status Codes: