REST Endpoints

From Obsidian Scheduler
Revision as of 00:55, 7 January 2013 by Carfey (talk | contribs)
Jump to navigationJump to search

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


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

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/{jobId}

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
    },
    {
      "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",
  "effectiveDate": "2012-01-10T15:33:00-0800",
  "endDate": "2013-01-10T15:33:00-0800",
  "hosts": [
    "host1",
    "host2"
  ],
  "minExecutionDuration": "1s",
  "maxExecutionDuration": "5m",
  "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 mandatory cron-style schedule for the job. If not ENABLED, this should 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.
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".
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}

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

Sample Request 

{
  "jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
  "nickname": "testCreateMixedHostsAndParams",
  "pickupBufferMinutes": 5,
  "recoveryType": "NONE",
  "hosts": [
    "host1",
    "host2"
  ],
  "minExecutionDuration": "1s",
  "maxExecutionDuration": "5m",
  "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.
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".
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.


DELETE an existing job

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

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

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
    },
    {
      "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

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"
}

Request Format

Field Required? Notes
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. 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.

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 jobs that are assigned to the specified host(s) are included. Supports multiple values.
start N Start date for the job schedules to return (inclusive). Defaults to current minute.
end N End date for the job schedules to return (inclusive). Defaults to a day after the start time. Must be after the start time.

Sample Response (with inline comments) 

{
  "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",
      "status": "FAILED",
      "job": {
        "recoveryType": "NONE",
        "pickupBufferMinutes": 2,
        "jobId": 43,
        "nickname": "jobThatChainsOthers",
        "activeSchedule": {
          "jobScheduleId": 44,
          "schedule": "@hourly",
          "status": "ENABLED",
          "endDate": "2013-01-06T17:44:00-0800",
          "effectiveDate": "2013-01-06T16:03:00-0800"
        },
        "jobClass": "someclass"
      },
      // 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",
        "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

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/job_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"
}

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.

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. Resonses will contain all the same details as a single record from a /job_runtimes GET request, with the addition of the output element, which contains saved job results.


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",
    "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"
      },
      "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"
      }
    ]
  }
}


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
  }
}


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

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.

Retrieved from "https://wiki.obsidianscheduler.com/doc/index.php?title=REST_Endpoints&oldid=671"