REST Endpoints
This page documents the format of each available REST endpoint.
For information on data formats, valid enumerations values, common behaviour and more, see the primary REST API page.
As of Obsidian 2.3, all endpoints have corresponding bean classes that can be used with JSON object mappers like Gson. If you wish to use these, please review bean classes for information on serialization of Obsidian's custom types.
Job Endpoints
GET a list of jobs
GET http(s)://localhost/rest/jobs[?host=host1&activeStatus=ENABLED&nickname=jobname¶m_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:
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. Returns a 404 if not found.
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]
Response bean class: com.carfey.ops.api.bean.history.RuntimeListing
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. |
| startKey | N | If requesting the next page of results from a previous call, set it to the returned nextPageStartKey.
|
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
Response bean class: com.carfey.ops.api.bean.history.RuntimeListing
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
Request bean class: com.carfey.ops.api.bean.history.RuntimeSubmissionRequest
Response bean class: com.carfey.ops.api.bean.history.RuntimeSubmissionResult
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}
Response bean class: com.carfey.ops.api.bean.history.RuntimeResult
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
Response bean class: com.carfey.ops.api.bean.history.RuntimeResubmissionResult
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
Response bean class: com.carfey.ops.api.bean.history.JobInterruptResult
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, and it is capable of shutting down. 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]
Response bean class: com.carfey.ops.api.bean.schedule.RuntimePreviewListing
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
Response bean class: com.carfey.ops.api.bean.schedule.RuntimePreviewListing
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.
Job Chain Endpoints
Available as of version 2.4.
GET a list of job chains
GET http(s)://localhost/rest/chains[?active=true&sourceJobId=123&targetJobId=456]
Response bean class: com.carfey.ops.api.bean.job.JobChainListing
Returns a list of configured job chains, optionally filtered by query string parameters.
Query String Parameters
| Field | Required? | Notes |
|---|---|---|
| active | N | Limits results to those matching the active flag (true/false). |
| sourceJobId | N | Limits results to those matching the supplied source job ID. |
| targetJobId | N | Limits results to those matching the supplied target job ID. |
Sample Response (with inline comments)
{
"jobChains": [
{
"jobChainId": 1,
"schedule": "* * * * *", // optional
"active": true,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Order Export Job",
"interruptable": true,
"jobClass": "com.example.OrderExportJob",
"autoRetryCount": 0,
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"chainAll": false,
"revision": 5
},
"triggerStates": ["FAILED","CONDITIONAL"],
"resultConditions": [
{
"variableName": "exportFile",
"operator":"EXISTS",
"values":[] // empty list when values do not apply
},
{
"variableName":"fileSize",
"operator":"GREATER_THAN",
"values":["0"] // list with one element when multiples aren't applicable
},
{
"variableName":"status",
"operator":"IN",
"values":["EXPORTED", "ZIPPED"]
}
]
},
{
"jobChainId": 2,
"active": false,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Customer Export Job",
"interruptable": true,
"jobClass": "com.example.CustomerExportJob",
"autoRetryCount": 0,
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"chainAll": false,
"revision": 5
},
"triggerStates": ["COMPLETED"],
"resultConditions": [] // only populated when CONDITIONAL state is used
}
]
}
GET details of an existing job chain
GET http(s)://localhost/rest/chains/{jobChainId}
Response bean class: com.carfey.ops.api.bean.job.JobChain
Returns details of a configured job chain, or a 404 if not found. Contains the same set of fields as the job chain listing endpoint.
Sample Response (with inline comments)
{
"jobChainId": 1,
"schedule": "* * * * *", // optional
"active": true,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Order Export Job",
"interruptable": true,
"jobClass": "com.example.OrderExportJob",
"autoRetryCount": 0,
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"chainAll": false,
"revision": 5
},
"triggerStates": ["FAILED", "CONDITIONAL"],
"resultConditions": [ // only populated when CONDITIONAL state is used
{
"variableName": "exportFile",
"operator":"EXISTS",
"values":[]
},
{
"variableName":"fileSize",
"operator":"GREATER_THAN",
"values":["0"]
},
{
"variableName":"status",
"operator":"IN",
"values":["EXPORTED", "ZIPPED"]
}
]
}
Scheduling Hosts Endpoints
GET a list of known scheduling hosts
GET http(s)://localhost/rest/hosts
Response bean class: com.carfey.ops.api.bean.host.HostListing
Returns a list of known hosts. These are either running or recently 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}
Response bean class: com.carfey.ops.api.bean.host.HostDetail
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}
Request bean class: com.carfey.ops.api.bean.host.HostUpdateRequest
Response bean class: com.carfey.ops.api.bean.host.HostDetail
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.
The following endpoints allow for managing of Custom Calendars.
GET a list of custom calendars
GET http(s)://localhost/rest/calendars
Response bean class: com.carfey.ops.api.bean.calendar.CustomCalendarListing
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}
Response bean class: com.carfey.ops.api.bean.calendar.CustomCalendar
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/
Request bean class: com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest
Response bean class: com.carfey.ops.api.bean.calendar.CustomCalendar
Updates the name and dates of the requested calendar, or a 404 if not found.
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 updates to an existing custom calendar
PUT http(s)://localhost/rest/calendars/{id}
Request bean class: com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest
Response bean class: com.carfey.ops.api.bean.calendar.CustomCalendar
Updates the name and dates of the requested calendar, or a 404 if not found.
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
}
