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

Enumerations

Below are valid values for commonly used fields in the API.

Job Status

• ENABLED
• DISABLED
• UNSCHEDULED_ACTIVE or UNSCHEDULED ACTIVE
• CHAIN_ACTIVE or CHAIN ACTIVE
• AD_HOC_ACTIVE or AD HOC ACTIVE

Job History Status

• READY
• RUNNING
• COMPLETED
• FAILED
• MISSED
• DIED
• CONFLICTED
• OVERLAPPED
• ABANDONED
• CONFLICT_MISSED or CONFLICT MISSED
• CHAIN_SKIPPED or CHAIN SKIPPED

Job Recovery Type

• NONE
• LAST
• ALL
• CONFLICTED

Job Parameter Type

• STRING
• INTEGER
• LONG
• DECIMAL
• BOOLEAN
• CLASS

Job Endpoints

GET a list of jobs

GET http(s)://localhost/rest/jobs[?host=host1&activeStatus=ENABLED]

Returns a list of configured jobs, optionally filtered by query string parameters.

Query String Parameters

Field	Required?	Notes
activeStatus	N	Restricts the preview to the selected statuses. See Enumerations for valid values. Supports multiple values.
effectiveDate	N	If querying by activeStatus, this allows you to indicate what point in time to compare against the job status. Defaults to next minute.
host	N	If specified, only jobs that run on the specified host(s) are included. Supports multiple values.

Sample Response

{
  "jobs": [
    {
      "recoveryType": "NONE",
      "jobId": 33,
      "pickupBufferMinutes": 5,
      "nickname": "jobOne",
      "activeSchedule": {
        "jobScheduleId": 34,
        "status": "CHAIN ACTIVE",
        "endDate": "2999-12-31T23:59:00-0800",
        "effectiveDate": "2013-01-06T14:37:00-0800"
      },
      "jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
      "revision": 0
    },
    {
      "recoveryType": "CONFLICTED",
      "jobId": 35,
      "pickupBufferMinutes": 123,
      "nickname": "jobTwo",
      "activeSchedule": {
        "jobScheduleId": 37,
        "status": "CHAIN ACTIVE",
        "endDate": "2013-01-08T14:34:00-0800",
        "effectiveDate": "2013-01-07T14:34:00-0800"
      },
      "jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
      "revision": 2
    }
  ]
}

GET details of an existing job

GET http(s)://localhost/rest/jobs/33

Returns full job information, including all historical schedules and parameter information.

Sample Response (with inline comments)

{
  "schedules": [
    {
      "effectiveDate": "2013-01-08T15:15:00-0800",
      "endDate": "2013-01-10T15:15:00-0800",
      "status": "CHAIN ACTIVE",
      "jobScheduleId": 35
    },
    {
      "effectiveDate": "2013-01-10T15:16:00-0800",
      "endDate": "2999-12-31T23:59:00-0800",
      "status": "DISABLED",
      "jobScheduleId": 36
    }
  ],
  "currentJobScheduleId": 35, // id of the item in "schedules" which is active right now
  "jobClassDescription": "This job cleans up log history beyond the configured age.", // returned only if Job is annotated with @Description
  "hosts": [
    "host1"
  ],
  "job": {
    "jobId": 34,
    "revision": 0,
    "jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
    "nickname": "testCreateWithEffectiveDatesAndParams",
    "pickupBufferMinutes": 5,
    "recoveryType": "NONE",
    "minExecutionDuration" : "1s", // only present when defined on job
    "maxExecutionDuration" : "10m" // only present when defined on job
  },
  "parameters": [
    {
      "name": "level",
      "type": "STRING",
      "allowMultiple": true,
      "required": true,
      "values": [ "WARN", "ERROR" ],
      "defaultValue": "ALL",
      "defined": true // true if defined by @Configuration annotation on the job
    },
    {
      "name": "maxAgeDays",
      "type": "INTEGER", // see Enumerations above for valid values
      "allowMultiple": false,
      "required": true,
      "values": [ "60" ], // values is always a list for consistency, even when allowMultiple is false
      "defaultValue": "120",
      "defined": true
    }
  ]
}

POST a new job

POST http(s)://localhost/rest/jobs

Creates a new job with an initial schedule.

Sample Request

{
  "jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
  "nickname": "testCreateMixedHostsAndParams",
  "pickupBufferMinutes": 5,
  "recoveryType": "NONE",
  "state": "ENABLED",
  "schedule": "@daily",
  "hosts": [
    "host1",
    "host2"
  ],
  "minExecutionDuration": "1s",
  "maxExecutionDuration": "5m",
  "effectiveDate": "2012-01-10T15:33:00-0800",
  "endDate": "2013-01-10T15:33:00-0800",
  "parameters": [
    {
      "name": "level",
      "type": "STRING",
      "value": "ERROR"
    },
    {
      "name": "level",
      "type": "STRING",
      "value": "WARN"
    }
  ]
}

Request Format

Field	Required?	Notes
jobClass	Y	Fully qualified class name of the job. Max 255 chars.
nickname	Y	Unique nickname for the job. Max 50 chars.
pickupBufferMinutes	Y	Pickup buffer minutes. Integer greater than zero.
recoveryType	Y	Recovery type as defined in Enumerations.
state	Y	Initial schedule's job status as defined in Enumerations.
schedule	Y/N	If state is ENABLED, the cron-style schedule for the job. If not ENABLED, this may be omitted.
effectiveDate	N	Optional effective date for the initial schedule. If not set, this defaults to next minute. Until this date is reached, the job is DISABLED.
endDate	N	Optional end date for the initial schedule. If set, the job will become DISABLED after this date passes.
hosts	N	Zero or more host names that this job may run on. If none set, the job may run on any host.
parameters	Y/N	TODO
minExecutionDuration	N	The minimum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
maxExecutionDuration	N	The maximum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".

Responses have the same format as GET.

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 (supports multiple jobs)

GET http(s)://localhost/rest/job_runtimes/previews[?jobId=1&jobId=2&start=1356987599000&end=1357510546000]

Returns a preview of runtimes, optionally filtered based on the supplied query string parameters. This is useful to see when jobs will run during a given time period. Note that these are an estimate of runtimes and cannot account for overlapped jobs, schedule changes or other issues that may result in altered execution times. Results are ordered by scheduled time descending.

Note: The capped field in the response indicates that there were too many results to return (i.e. exceeded maxRecords as configured in the Admin System tab). If you are hitting this condition, try limiting your date range or other parameters. Due to the nature of the runtime preview, paging is not feasible.

Query String Parameters

Field	Required?	Notes
jobId	N	Restricts the preview to the selected jobs. Supports multiple values.
start	N	Start date for the runtimes to preview (inclusive). Defaults to next minute.
end	N	End date for the runtimes to preview (inclusive). Defaults to a day after the start time. Must be after the start time.

Sample Response

{
  "capped": false,
  "runtimes": [
    {
      "jobId": 36,
      "nickname": "jobOne",
      "schedule": "* * * * *",
      "scheduledTime": "2013-01-06T15:31:00-0800",
      "scheduleEffectiveDate": "2013-01-06T13:50:00-0800",
      "scheduleEndDate": "2999-12-31T23:59:00-0800"
    },
    {
      "jobId": 37,
      "nickname": "jobTwo",
      "schedule": "* * * * *",
      "scheduledTime": "2013-01-06T15:30:00-0800",
      "scheduleEffectiveDate": "2013-01-06T13:50:00-0800",
      "scheduleEndDate": "2999-12-31T23:59:00-0800"
    }
  ]
}

GET a list of runtime previews for an existing job

GET http(s)://localhost/rest/jobs/{jobId}/runtimes/previews

This endpoint is equivalent the other runtime preview endpoint (see preceding item) with a URL like the following: GET http(s)://localhost/rest/job_runtimes/previews?jobId={jobId}

Other than the jobId, all other query string parameters from the multi-job endpoint are supported.

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. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

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. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

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.