REST Endpoints

For information on how common behaviour of endpoints, see Common Behaviour below.

The supported endpoints are listed below. Endpoints may be accessed either through HTTP or HTTPS.

Common Behaviour

• For GET and DELETE, parameterization is done via request parameters, and not JSON body. Supported parameters are simple and primarily provide search options and simple flags.
• All non-200 responses will always return a JSON response in the following format. One or more errors may be returned in the errors property.

{ 
    "errors":["nickname is required.", "jobClass is required."]
}

{ 
    "errors":["Resource not found"]
}

• If a request does not pass validation or if an action cannot be performed, a 400 status code will be returned. This may happen if required fields are omitted, in an invalid format, or an action cannot be performed in the current context.
• If a JSON payload contains unexpected fields, a 400 status code will be returned.
• If a resource with the specified identifier could not be found, a 404 status code will be returned. For example, this would occur if you attempt to load a job with an ID that does not exist.
• If an incorrect method is used on an endpoint (e.g. DELETE on a job runtime), a 405 status code will be returned.
• If no valid basic authentication is provided (see REST API), a 401 status code will be returned.
• If no endpoint exists at the requested path, a 404 status code will be returned.
• If the Content-Type header of a PUT or POST request is not application/json, a 415 status code will be returned.
• If the server encounters an unexpected error, a 500 status code will be returned.

Date Formats

Since scheduling is inherently linked to time zones and is not fully represented by a UTC time, all times in the API are returned in the following string format. Note the trailing timezone indicator which indicates the UTC offset.

yyyy-MM-dd'T'HH:mm:ssZ

For example, the last second of 2012 PST is:

2012-12-31T23:59:59-0800

Date Inputs

While dates are always output in the same format, dates in query strings or in JSON payloads can use either the standard output format shown above, an abbreviated form that contains no timezone offset and assumes server time, or the UTC time represented as milliseconds since the epoch. For example, the last second of 2012 EST is:

2012-12-31T23:59:59-0800

Or, interpreted in the server time zone:

2012-12-31T23:59:59

Or, as milliseconds since the epoch:

1356987599000

Job Endpoints

GET a list of jobs

Coming soon...

POST a new job

Coming soon...

GET details of an existing job

Coming soon...

PUT updates to an existing job

Coming soon...

DELETE an existing job

Coming soon...

GET a list of an existing job's schedules

Coming soon...

POST a new schedule to an existing job

Coming soon...

Runtimes Endpoints (i.e. Job History)

GET a list of a job's scheduled runtimes

Coming soon...

POST a new scheduled runtime for an existing job (i.e. submit a one-time or ad hoc run)

Coming soon...

GET a list of scheduled runtimes (supports multiple jobs)

Coming soon...

GET details of an existing scheduled (or completed) job runtime

Coming soon...

POST a resubmission request for a failed job runtime

Coming soon...

Runtime Preview Endpoints

GET a list of runtime previews for an existing job

Coming soon...

GET a list of runtime previews (supports multiple jobs)

Coming soon...

Scheduling Hosts Endpoints

GET a list of known scheduling hosts

GET http(s)://localhost/rest/hosts

Returns a list of known hosts. These are either running or shut down abnormally. Hosts that shut down normally are unregistered on shutdown. Note that returned IDs are transient and may change after startup or shutdown or a node.

Sample response:

{
  "hosts": [
    {
      "id": 32,
      "name": "production1",
      "heartbeatTime": "2013-01-05T21:15:59-0800",
      "enabled": true
    },
    {
      "id": 33,
      "name": "production2",
      "heartbeatTime": "2013-01-05T21:15:59-0800",
      "enabled": false
    }
  ]
}

GET details on an existing scheduling host

GET http(s)://localhost/rest/hosts/{id}

Alternate (by host name): GET http(s)://localhost/rest/hosts/names/{name}

Returns the requested host, or a 404 if not found.

Note: The name field corresponds to the host name, as described here. Explicit host names should be set if you intend to rely known host names in this endpoint.

Sample response:

{
  "host": {
    "id": 33,
    "name": "production1",
    "heartbeatTime": "2013-01-05T21:18:18-0800",
    "enabled": false
  }
}

PUT updates to an existing scheduling host

GET http(s)://localhost/rest/hosts/{id}

Alternate (by host name): GET http(s)://localhost/rest/hosts/names/{name}

Updates the enabled status of the requested host, or a 404 if not found. This endpoint is used to enable or disable scheduling nodes.

Note: The name field corresponds to the host name, as described here. Explicit host names should be set if you intend to rely known host names in this endpoint.

Sample Request

{
  "enabled": false
}

Request Format

Field	Required?	Notes
enabled	Y	Should this host should be enabled?

Responses have the same format as GET.