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.
Pagination¶
When the results set is larger than a configured amount, the data is broken up into pages using the limit and offset parameters.
Paginated endpoints will provide information about the total amount of items available along with links to the previous and next pages (where available) in the returned JSON data.
-
GET
/
(any)/
Query Parameters: - limit – the amount of record to limit a page of results to.
- offset – the starting position of the query in relation to the complete set of unpaginated items
Response JSON Object: - count (int) – the total number of results available
- previous (string) – the URL to the previous page of results (if available)
- next (string) – the URL to the next page of results (if available)
Example request:
HTTP/1.1 200 OK Content-Type: application/json { "count": 50, "next": "http://sbm.example.org/api/v1/enpoint/?limit=10&offset=30", "previous": "http://smb.example.org/api/v1/endpoint/?limit=10&offset=10", "results": [] }
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: - 201 Created – token successfully created.
- 400 Bad Request – an email address was not provided or was invalid.
- 401 Unauthorized – the token is invalid/missing.
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: - 200 OK – no error.
- 401 Unauthorized – the token is invalid/missing.
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: - 200 OK – no error.
- 401 Unauthorized – the token is invalid/missing.
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: - 200 OK – no error
- 401 Unauthorized – the token is invalid/missing.
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: - 200 OK – no error.
- 401 Unauthorized – the token is invalid/missing.
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: - 201 Created – created.
- 400 Bad Request – invalid data.
- 401 Unauthorized – the token is invalid/missing.
-
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: - 200 OK – updated.
- 400 Bad Request – invalid data.
- 401 Unauthorized – the token is invalid/missing.
-
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: - 200 OK – no error
- 401 Unauthorized – the token is invalid/missing.
-
POST
/metrics/
Starts a task that fires all scheduled metrics.
Status Codes: - 200 OK – no error
- 401 Unauthorized – the token is invalid/missing.
-
GET
/health/
Returns a basic health check status.
Status Codes: - 200 OK – no error
- 401 Unauthorized – the token is invalid/missing.