REST Endpoints

For information on 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

When a date only is input or output (as with custom calendars), it is always in the following format:

2012-12-31

Date & Time Inputs

While datetimes are always output in the same format, datetimes 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 PST 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

JSON Bean Classes

As of version 2.3, Obsidian comes bundled with simple bean classes in the package com.carfey.ops.api.bean that can be used to serialize JSON requests and deserialize responses into plain old Java objects (POJOs). These classes are tested with Gson since that is what Obsidian uses internally, but you can integrate it with the JSON library of your choosing. Obsidian uses custom types for dates and datetimes, so see the following section on how to configure JSON serialization correctly.

Each endpoint documents the appropriate bean class to use.

Serializing & Deserializing Date Types

Since the Obsidian REST API uses its own specific date formats to fully represent scheduled times including their time zones, you will have to use custom serializers to properly use the supplied bean classes. Doing this is simple, and we've provided a sample below for Gson, plus a generic example to show you how to parse and format dates appropriately, which you can adapt for use in JSON other libraries.

GSON Serialization:

import com.carfey.jdk.lang.Date;
import com.carfey.jdk.lang.DateTime;

import com.carfey.jdk.lang.Date;
import com.carfey.jdk.lang.DateFormat.ParseException;
import com.carfey.jdk.lang.DateTime;
import com.carfey.jdk.text.Json;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;


public class GsonDemo {
	public static void main(String[] args) throws ParseException {

        // Set up the custom serializers for date types
        GsonBuilder gb = new GsonBuilder();
        gb.registerTypeAdapter(Date.class, Json.REST_SERIALIZER);
        gb.registerTypeAdapter(DateTime.class, Json.REST_SERIALIZER);
        Gson gson = gb.create();

        // The Gson instance can now be used with all Obsidian REST bean classes
        SampleBean sample = new SampleBean();
        String stringValue = gson.toJson(sample);
        System.out.println(stringValue);

        SampleBean rebuilt = gson.fromJson(stringValue, SampleBean.class);
        System.out.println(rebuilt);
    }

    private static class SampleBean {
        private com.carfey.jdk.lang.Date date = new Date();
        private com.carfey.jdk.lang.DateTime dateTime = new DateTime();
        public Date getDate() {
            return date;
        }
        public void setDate(Date date) {
            this.date = date;
        }
        public DateTime getDateTime() {
            return dateTime;
        }
        public void setDateTime(DateTime dateTime) {
            this.dateTime = dateTime;
        }
        @Override
        public String toString() {
            return "SampleBean [date=" + date + ", dateTime=" + dateTime + "]";
        }

    }
}

Output:

{"date":"2013-10-30","dateTime":"2013-10-30T22:04:24-0700"}
SampleBean [date=20131030, dateTime=20131030 10:04:24:000 PM -0700]

Generic Date Parsing and Formatting Example:

// converting REST date time formats (serialize and deserialize)
com.carfey.jdk.lang.DateFormat dateTimeFormat = new com.carfey.jdk.lang.DateFormat("yyyy-MM-dd'T'HH:mm:ssZ");

com.carfey.jdk.lang.DateTime dateTime = new com.carfey.jdk.lang.DateTime();
String dateTimeString = dateTimeFormat.format(dateTime);
com.carfey.jdk.lang.DateTime asDateTime = dateTimeFormat.parse(dateTimeString);
System.out.println(asDateTime);



com.carfey.jdk.lang.DateFormat dateFormat = new com.carfey.jdk.lang.DateFormat("yyyy-MM-dd");

com.carfey.jdk.lang.Date date = new com.carfey.jdk.lang.Date();
String dateString = dateTimeFormat.format(date);
com.carfey.jdk.lang.Date asDate = dateTimeFormat.parse(dateString).getDate();
System.out.println(asDate);

Output:

20131105 06:10:41:000 PM -0800
20131105

Job Endpoints

GET a list of jobs

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

Response bean class: com.carfey.ops.api.bean.job.JobListing

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 name(s) are included. Supports multiple values.
nickname	N	If specified, only jobs matching the supplied nickname are returned. Wildcards may be included to support partial matches by using %, or exact literals can be used. For example, to find all jobs containing the word "order", use "%order%". Supports multiple values. Available from version 1.5.2 forward.
param_parameterName	N	If specified, values starting with param_ can be used to match only on jobs with specific job parameter values, either custom or defined. If multiple values for the same query parameter starting with param_ are supplied, a job is matched if any of its configured values match one of the supplied values. If param_ filters with separate names are used, each must have a matching value for the job to be returned. Usage note: This can be used to tag jobs with searchable metadata by configuring custom parameters. For example, if jobs belong to logical groups, you may create a custom parameter on applicable jobs named "group" and use a query like the following to find jobs belonging to the "customer" or "order" groups: GET http(s)://localhost/rest/jobs[?param_group=customer&param_group=order] Available from version 1.5.2 forward.

Sample Response

{
  "jobs": [
    {
      "recoveryType": "NONE",
      "jobId": 33,
      "pickupBufferMinutes": 5,
      "nickname": "jobOne",
      "interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
      "autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
      "minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
      "maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
      "chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
      "activeSchedule": {
        "jobScheduleId": 34,
        "status": "CHAIN ACTIVE",
        "endDate": "2999-12-31T23:59:00-0800",
        "effectiveDate": "2013-01-06T14:37:00-0800",
        "customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
      },
      "jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
      "revision": 0
    },
    {
      "recoveryType": "CONFLICTED",
      "jobId": 35,
      "pickupBufferMinutes": 123,
      "nickname": "jobTwo",
      "interruptable": false
      "autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
      "minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
      "maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
      "chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
      "activeSchedule": {
        "jobScheduleId": 37,
        "status": "CHAIN ACTIVE",
        "endDate": "2013-01-08T14:34:00-0800",
        "effectiveDate": "2013-01-07T14:34:00-0800",
        "customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
      },
      "jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
      "revision": 2
    }
  ]
}

GET details of an existing job

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

Response bean class: com.carfey.ops.api.bean.job.JobDetail

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": "ENABLED",
      "schedule": "* * * * *",
      "jobScheduleId": 35,
      "customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
    },
    {
      "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",
    "interruptable": false, // indicates if job can be interrupted (as 1.5.1)
    "autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
    "minExecutionDuration" : "1s", // only present when defined on job
    "maxExecutionDuration" : "10m" // only present when defined on job
    "chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
  },
  "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

Request bean class: com.carfey.ops.api.bean.job.JobCreationRequest

Response bean class: com.carfey.ops.api.bean.job.JobDetail

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",
  "effectiveDate": "2012-01-10T15:33:00-0800",
  "endDate": "2013-01-10T15:33:00-0800",
  "hosts": [
    "host1",
    "host2"
  ],
  "minExecutionDuration": "1s",
  "maxExecutionDuration": "5m",
  "chainAll": false,  // as of 2.0
  "autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
  "customCalendarId": null, // as of 2.0
  "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 before 1.5.2, after which it is 255 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 mandatory cron-style schedule for the job. If not ENABLED, this should be omitted.
effectiveDate	N	Optional effective date for the initial schedule, with no seconds specified. 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, with no seconds specified. If set, the job will become DISABLED after this date passes.
customCalendarId	N	As of Obsidian 2.0. Optional custom calendar id.
hosts	N	Zero or more host names that this job may run on. If none set, the job may run on any host.
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".
autoRetryCount	Y	As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if none are desired.
chainAll	N	As of Obsidian 2.0. Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created.
parameters	Y/N	Zero or more parameter definitions. If a job defines required parameters with the @Configuration annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in Enumerations. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.

Responses have the same format as GET.

PUT updates to an existing job

PUT http(s)://localhost/rest/jobs/{jobId}

Request bean class: com.carfey.ops.api.bean.job.JobUpdateRequest

Response bean class: com.carfey.ops.api.bean.job.JobDetail

Updates a job's configuration. Does not support schedule changes or additions. For schedule changes, see POST a new schedule to an existing job.

As of Obsidian 2.3, this endpoint will only update fields that are supplied in the request, similar to a PATCH request. You may update one or more fields as desired.

Sample Request

{
  "jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
  "nickname": "testCreateMixedHostsAndParams",
  "pickupBufferMinutes": 5,
  "recoveryType": "NONE",
  "hosts": [
    "host1",
    "host2"
  ],
  "minExecutionDuration": "1s",
  "maxExecutionDuration": "5m",
  "autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
  "chainAll": false,
  "parameters": [
    {
      "name": "level",
      "type": "STRING",
      "value": "ERROR"
    },
    {
      "name": "level",
      "type": "STRING",
      "value": "WARN"
    }
  ]
}

Request Format

Field	Required?	Notes
jobClass	N	Fully qualified class name of the job. Max 255 chars.
nickname	N	Unique nickname for the job. Max 50 chars.
pickupBufferMinutes	N	Pickup buffer minutes. Integer greater than zero.
recoveryType	N	Recovery type as defined in Enumerations.
hosts	N	Zero or more host names that this job may run on. If none set, the job may run on any host.
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: "2h".
autoRetryCount	N	As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if none are desired.
chainAll	N	As of Obsidian 2.0. Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created.
parameters	N	Zero or more parameter definitions. If a job defines required parameters with the @Configuration annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in Enumerations. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.

Responses have the same format as GET.

DELETE an existing job

DELETE http(s)://localhost/rest/jobs/{jobId}[?cascade=true]

Response bean class: com.carfey.ops.api.bean.job.JobDetail

Deletes a job and its history.

Query String Parameters

Field	Required?	Notes
cascade	N	If set to true, all job conflict and chain definitions for this job will also be deleted. If not set, or set to false, any existing job conflicts or chain definitions will cause the request to fail.

Responses have the same format as GET, and return the final state of the job before the delete.

GET a list of an existing job's schedules

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

Response bean class: com.carfey.ops.api.bean.job.JobScheduleListing

Returns historical schedules for a job. This is a basically subset of the primary GET endpoint for an existing job.

Sample Response

{
  "schedules": [
    {
      "effectiveDate": "2012-01-06T15:53:00-0800",
      "endDate": "2012-08-06T15:53:00-0700",
      "schedule": "@hourly",
      "status": "ENABLED",
      "jobScheduleId": 37,
      "customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
    },
    {
      "effectiveDate": "2015-01-06T15:53:00-0800",
      "endDate": "2016-01-06T15:53:00-0800",
      "status": "AD HOC ACTIVE",
      "jobScheduleId": 38
    }
  ],
  "jobId": 35,
  "currentJobScheduleId": 38
}

POST a new schedule to an existing job

POST http(s)://localhost/rest/jobs/{jobId}/schedules

Request bean class: com.carfey.ops.api.bean.schedule.ScheduleCreationRequest

Response bean class: com.carfey.ops.api.bean.job.JobScheduleListing

Creates a new schedule for the job. This may be used to immediately change a job's scheduling state, or to schedule a future change. Creating a new schedule automatically splits and merges existing schedules. For example, if you have an enabled job and you disabled it for a day, the job will automatically re-enable after that day.

Sample Request

{
  "state": "ENABLED",
  "schedule": "@daily",
  "effectiveDate": "2012-01-10T15:33:00-0800",
  "endDate": "2013-01-10T15:33:00-0800",
  "customCalendarId": 123 // if desired, the custom calendar (as of 2.0)
}

Request Format

Field	Required?	Notes
state	Y	The schedule's job status as defined in Enumerations.
schedule	Y/N	If state is ENABLED, the mandatory cron-style schedule for the job. If not ENABLED, this should be omitted.
effectiveDate	N	Optional effective date for the schedule, with no seconds specified. If not set, this defaults to next minute. Until this date is reached, the job is DISABLED.
endDate	N	Optional end date for the schedule, with no seconds specified. If set, the job will become DISABLED after this date passes.
customCalendarId	N	As of Obsidian 2.0, optional custom calendar for schedule.

Responses have the same format as GET.

Runtimes Endpoints (i.e. Job History)

GET a list of scheduled runtimes (supports multiple jobs)

GET http(s)://localhost/rest/job_runtimes[?startKey=12345&status=RUNNING&host=host1]

Returns a list of scheduled or completed job runtimes (i.e. history), optionally filtered by query string parameters. Results are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of scheduled time.

Note: The nextPageStartKey field in the response indicates that there were too many results to return (i.e. exceeded maxRecords as configured in the Admin System tab). To fetch the next page of results, invoke the same endpoint with the startKey query string parameter set to the returned nextPageStartKey.

Query String Parameters

Field	Required?	Notes
jobId	N	Restricts the search to the selected jobs. Supports multiple values.
status	N	Restricts the search to the selected statuses. See Enumerations for valid values. Supports multiple values.
host	N	If specified, only job runtimes that are assigned to the specified host(s) are included. Supports multiple values.
start	N	Start date for the job runtimes to return (inclusive). Defaults to 24 hours ago (before 2.3, it defaulted to the current minute).
end	N	End date for the job runtimes to return (inclusive). Defaults to a day after the start time. Must be after the start time.

Sample Response (with inline comments)

{
  "nextPageStartKey" : "123",
  "start": "2013-10-31T23:59:00-0800", // the inclusive search from date (as of 2.3)
  "end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
  "runtimes": [
    {
      "heartbeatTime": "2013-01-06T16:05:00-0800",
      "jobRuntimeId": 8,
      "adHoc": false,
      "pickupTime": "2013-01-06T16:04:00-0800",
      // present when this job was resubmitted from another job runtime
      "resubmissionSource": {
        "jobRuntimeId": 10,
        "status": "READY",
        "scheduledTime": "2013-01-06T16:06:00-0800"
      },
      "endTime": "2013-01-06T16:05:00-0800",
      "revision": 1,
      "resubmission": false,
      "scheduledTime": "2013-01-06T16:04:00-0800",
      "autoRetryCount": 2, // present if this job was auto-retried from a failure (as of 2.3)
      "status": "FAILED",
      "error": { // present if the job fails
         "message": "arg was null",
         "detail": "stack trace..."
      },
      "job": {
        "recoveryType": "NONE",
        "pickupBufferMinutes": 2,
        "jobId": 43,
        "nickname": "jobThatChainsOthers",
        "interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
        "autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
        "minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
        "maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
        "revision" : 0, //  Present as of 2.3
        "activeSchedule": {
          "jobScheduleId": 44,
          "schedule": "@hourly",
          "status": "ENABLED",
          "endDate": "2013-01-06T17:44:00-0800",
          "effectiveDate": "2013-01-06T16:03:00-0800",
          "customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
        },
        "jobClass": "someclass"
      },
      // optional interruption element if job execution was interrupted (as of version 1.5.1)
      "interruption" : {
          "requester": "userName",
          "requestTime": "2013-01-06T16:04:54-0800",
          "interruptTime":"2013-01-06T16:04:56-0800" // this time will be set if successfully interrupted (otherwise not present)
      },
      // contains a list of job runtimes that were chained from this job runtime
      "chainTargets": [
        {
          "trigger": true,
          "detail": "chained it",
          "jobRuntimeId": 9,
          "job": {
            "jobId": 44,
            "nickname": "jobThatGetsChained"
          },
          "scheduledTime": "2013-01-06T16:05:00-0800"
        }
      ],
      "executionType": "Resubmission" // when present, indicates it executed as a "Resubmission", "Chained", or "Ad Hoc" job
    },
    {
      "jobRuntimeId": 9,
      "adHoc": false,
      "revision": 0,
      "resubmission": false,
      "scheduledTime": "2013-01-06T16:05:00-0800",
      "status": "READY",
      "job": {
        "recoveryType": "NONE",
        "pickupBufferMinutes": 2,
        "jobId": 44,
        "nickname": "jobThatGetsChained",
        "autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
        "minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
        "maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
        "revision" : 0, //  Present as of 2.3
        "activeSchedule": {
          "jobScheduleId": 45,
          "schedule": "@hourly",
          "status": "ENABLED",
          "endDate": "2013-01-06T17:44:00-0800",
          "effectiveDate": "2013-01-06T16:03:00-0800"
        },
        "jobClass": "someclass2"
      },
      // when present, this includes this runtime was chained as a result of another job runtime
      "chainSource": {
        "trigger": true,
        "detail": "chained it",
        "jobRuntimeId": 8,
        "job": {
          "jobId": 43,
          "nickname": "jobThatChainsOthers"
        },
        "scheduledTime": "2013-01-06T16:04:00-0800"
      },
      "chainTargets": [ ],
      "executionType": "Chained"
    }
  ]
}

GET a list of a job's scheduled runtimes

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

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

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

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

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

Allows for submission of an ad hoc job run (executed immediately), or a one-time run scheduled for a later time.

Note: The job must be in a valid state to allow for execution (i.e. "UNSCHEDULED ACTIVE", "ENABLED", or "AD HOC ACTIVE").

Sample Request

{
  "scheduledTime": "2013-02-06T16:40:00-0800",
  // Optional. Available as of 2.1.1. Parameters supplied for scheduled runtime which will be available to the job when executing.
 "parameters": [
    {
      "name": "level",
      "type": "STRING",
      "value": "ERROR"
    },
    {
      "name": "level",
      "type": "STRING",
      "value": "WARN"
    }
  ]
}

Request Format

Field	Required?	Notes
scheduledTime	N	The scheduled time, when the request is for a scheduled one-time run. If not supplied, the runtime is submitted for immediate execution as an ad hoc job.
parameters	N	Zero or more parameter definitions. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in Enumerations. To define multiple values for a single parameter name, simply include multiple items in the parameters collection. If the parameter name matches a parameter defined for the job, it must be of the same type.

Note: A jobRuntimeId is only returned in the case of an ad hoc run.

Sample Response (with inline comments)

{
  "jobRuntimeId": 2, // only returned for ad hoc submission (no scheduled time supplied)
  "jobId": 36,
  "scheduledTime": "2013-01-06T16:37:00-0800"
}

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

GET http(s)://localhost/rest/job_runtimes/{jobRuntimeId}

Returns detailed information for the requested job runtime. Responses will contain all the same details as a single record from a /job_runtimes GET request, with the addition of the output and parameters elements, which contain saved job results and runtime-specific parameters respectively.

Sample Response

{
  "runtime": {
    "heartbeatTime": "2013-01-06T16:27:00-0800",
    "jobRuntimeId": 2,
    "adHoc": false,
    "pickupTime": "2013-01-06T16:26:00-0800",
    "endTime": "2013-01-06T16:27:00-0800",
    "revision": 6,
    "resubmission": false,
    "scheduledTime": "2013-01-06T16:26:00-0800",
    "runningHost": "test3",
    "status": "FAILED",
    "interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
    "autoRetryCount": 2, // present if this job was auto-retried from a failure (as of 2.3)
    "job": {
      "recoveryType": "NONE",
      "pickupBufferMinutes": 2,
      "jobId": 36,
      "nickname": "testWithOutput",
      "activeSchedule": {
        "jobScheduleId": 37,
        "schedule": "@hourly",
        "status": "ENABLED",
        "endDate": "2013-01-06T18:06:00-0800",
        "effectiveDate": "2013-01-06T16:25:00-0800",
        "customCalendarId": 123 // if configured, the custom calendar for this job (as of 2.0)
      },
      "jobClass": "someclass"
    },
    "chainTargets": [
      
    ],
    "output": [
      {
        "jobRuntimeResultId": 4,
        "name": "testname",
        "value": "testvalue",
        "valueType": "java.lang.String"
      },
      {
        "jobRuntimeResultId": 5,
        "name": "testname",
        "value": "testvalue2",
        "valueType": "java.lang.String"
      },
      {
        "jobRuntimeResultId": 6,
        "name": "testname2",
        "value": "testvalue3",
        "valueType": "java.lang.String"
      }
    ],
    // Parameters specified for ad-hoc or one-time runtime (as of 2.1.1). This does not include parameters defined at the job level.
    "parameters": [
      {
        "name": "level",
        "type": "STRING", // see Enumerations above for valid values
        "values": [ "WARN", "ERROR" ]
      },
      {
        "name": "maxAgeDays",
        "type": "INTEGER",
        "values": [ "60" ] // values is always a list for consistency
      }
    ]
  }
}

POST a resubmission request for a failed job runtime

POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/resubmissions

Allows for resubmission of a failed job runtime.

The request has no content.

Sample Response

{
  "resubmission": {
    "revision": 0,
    "jobId": 35,
    "resubmission": true,
    "scheduledTime": "2013-01-06T16:49:00-0800",
    "status": "READY",
    "jobRuntimeId": 2
  }
}

POST an interruption request to kill a running job

POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/interrupts

Available as of version 1.5.1

Allows for interruption of a currently running job runtime. This request can only be made once successfully.

An interruption request will result in the job being terminated, as long as it does not terminate naturally very soon after the request is made. Not all jobs can be terminated. See Interruptable Jobs for full details.

The request has no content.

Sample Response

{
  "interruption": {
    "requester": "apiUserName",
    "requestTime": "2013-01-06T16:49:00-0800"
  }
}

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 the current 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,
  "start": "2013-10-31T23:59:00-0800", // the inclusive search from date (as of 2.3)
  "end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
  "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

PUT 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.

Custom Calendar Endpoints

As of Obsidian 2.0. Format revised in 2.3.

GET a list of custom calendars

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

Returns a list of custom calendars.

Sample Response

{
  "customCalendars": [
    {
      "revision": 0,
      "dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
      "name": "Corporate Holidays 2013",
      "customCalendarId": 1
    },
    {
      "revision": 0,
      "dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
      "name": "Corporate Holidays 2014",
      "customCalendarId": 2
    }
  ]
}

GET details on an existing custom calendar

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

As of Obsidian 2.3.

Returns the requested custom calendar, or a 404 if not found..

Sample Response

{
  "revision": 0,
  "dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
  "name": "Corporate Holidays 2013",
  "customCalendarId": 1
}

POST a new Custom Calendar

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

Sample Request

{
   "name": "Cal1",
   "dates": ["2016-10-14" ,"2018-06-14"],
}

Request Format

Field	Required?	Notes
name	Y	Calendar name
dates	Y	Dates to exclude

Sample Response

{
  "revision": 0,
  "dates": ["2016-10-14" ,"2018-06-14"],
  "name": "Cal1",
  "customCalendarId": 1
}

PUT a Custom Calendar Update

PUT http(s)://localhost/rest/calendars/{id}

Sample Request

{
    "name": "Cal2",
    "dates": ["2018-06-13","2016-10-13"]
}

Request Format

Field	Required?	Notes
name	Y	Calendar name
dates	Y	Dates to exclude

Sample Response

{
  "revision": 1,
  "dates": ["2016-10-14" ,"2018-06-14"],
  "name": "Cal2",
  "customCalendarId": 1
}