Job Scheduler API

The Job Scheduler API allows you to create and manage jobs that will run one or more times in the future.

Overview

The Job Scheduler works by accepting requests for future notifications. Each job has a specific date or schedule and a user-specified callback URL to contact when the job fires. This callback URL is an entry point which tells your application that its times to process the job.

In addition, each job may include a payload which will be provided when notifying your application. In this way your application may provide contextual data needed to process the job in the future.

This is a RESTful API which is accessed over HTTP. Any language which can make HTTP requests can use the API to interact with the scheduler service. It accepts requests in XML or JSON, and can generate responses in XML or JSON (and in some cases plain text).

What's in a job?

A job structure has several fields that describe the job and it's payload. These fields and examples of both request and response documents in each of the supported formats are listed below:

Request Headers

These headers may be sent by your application to control the processing of the API call.

Response Headers

These headers will be included when responding to an API call.

Jobs API

List

https://job-sheduling.info/1/jobs

Provides a list of all job ids for the account. See an example text, JSON or XML response.

Get

https://job-sheduling.info/1/jobs/<id>

Retrieve the details of the specified job. See an example XML or JSON request and JSON or XML response.

Create One-time or Recurring Job

https://job-sheduling.info/1/jobs

Creates a new one-time or recurring job from the job detail document posted as the message body. This call returns either the job id for the full job details. See an example XML or JSON request and text, JSON or XML response.

Update Job

https://job-sheduling.info/1/jobs/<id>

Updates an existing one-time or recurring job from the job detail document posted as the message body. This call returns either the job id for the full job details. See an example XML or JSON request and text, JSON or XML response.

Delete Job

https://job-sheduling.info/1/jobs/<id>

Deletes an existing one-time or recurring job.

Create One-time Job

https://job-sheduling.info/1/jobs/<when>/<callback>

Alternative API call for creating a new one-time job which does not require building a request document. The time and callback URL are encoded in the request path, and the callback payload may optionally be included as the message body. If a payload in included, the Content-Type and X-Content-Signature request headers are copied to the corresponding fields describing the callback payload. See an example text, JSON or XML response.

ex. https://job-sheduling.info/1/jobs/2011-05-11T15%3A30%3A00Z/https%3A%2F%2Fexample.com

Create Recurring Job

https://job-sheduling.info/1/jobs/<cron>/<callback>

Alternative API call for creating a new recurring job which does not require building a request document. The cron expression and callback URL are encoded in the request path, and the callback payload may optionally be included as the message body. If a payload in included, the Content-Type and X-Content-Signature request headers are copied to the corresponding fields describing the callback payload. See an example text, JSON or XML response.

ex. https://job-sheduling.info/1/jobs/0+15+10+%3F+*+*/https%3A%2F%2Fexample.com

Example Documents

These are examples of formatted request and response documents:

Example JSON Request Document for a Recurring Job

{
  "url": "https://example.com/my-callback",
  "cron": "0 15 10 ? * *",
}

Example JSON Request Document for a Single Job (with optional fields)

{
  "url": "https://example.com/my-callback",
  "signature": "507aaa0733464499847c930db95983f8994ae266",
  "contentType": "text/plain",
  "data": "testing",
  "when": "2011-05-11T15:30:00Z"
}

Example JSON Response Document for a Recurring Job

{
  "id": "03ba07bc-0c8b-4a82-9a47-c65e7a8d24af"
  "account": "example"
  "url": "https://example.com/my-callback",
  "cron": "0 15 10 ? * *",
  "next": "2011-05-11T15:30:00Z"
}

Example JSON Response for a Single Job (with optional fields)

{
  "id": "03ba07bc-0c8b-4a82-9a47-c65e7a8d24af"
  "account": "example"
  "url": "https://example.com/my-callback",
  "signature": "507aaa0733464499847c930db95983f8994ae266",
  "contentType": "text/plain",
  "data": "testing",
  "when": "2011-05-11T15:30:00Z"
}

Example XML Request Document for a Recurring Job

<job>
  <url>https://example.com/my-callback</url>
  <cron>0 15 10 ? * *</cron>
</job>

Example XML Request Document for a Single Job (with optional fields)

<job>
  <url>https://example.com/my-callback</url>
  <signature>507aaa0733464499847c930db95983f8994ae266</signature>
  <contentType>text/plain</contentType>
  <data>testing</data>
  <when>2011-05-11T15:30:00Z</when>
</job>

<job>
  <id>03ba07bc-0c8b-4a82-9a47-c65e7a8d24af</id>
  <account>example</account>
  <url>https://example.com/my-callback</url>
  <cron>0 15 10 ? * *</cron>
  <next>2011-05-11T15:30:00Z</next>
</job>

Example XML Response for a Single Job (with optional fields)

<job>
  <id>03ba07bc-0c8b-4a82-9a47-c65e7a8d24af</id>
  <account>example</account>
  <url>https://example.com/my-callback</url>
  <signature>507aaa0733464499847c930db95983f8994ae266</signature>
  <contentType>text/plain</contentType>
  <data>testing</data>
  <when>2011-05-11T15:30:00Z</when>
</job>

Example Plain Text Response for Job Create

03ba07bc-0c8b-4a82-9a47-c65e7a8d24af

Example Plain Text Response for Job List

1,2,3

Example JSON Response for Job List

["1","2","3"]

Example XML Response for Job List

<jobs>
  <id>1</id>
  <id>2</id>
  <id>3</id>
</jobs>