::Go back to Oozie Documentation Index::
The Oozie Web Services API is a HTTP REST JSON API.
All responses are in UTF-8 .
Assuming Oozie is runing at OOZIE_URL , the following web services end points are supported:
Identical to the corresponding Oozie v0 WS API
This endpoint is for clients to perform protocol negotiation.
It support only HTTP GET request and not sub-resources.
It returns the supported Oozie protocol versions by the server.
Current returned values are 0, 1 .
Request:
GET /oozie/versions
Response:
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 . [0,1]
This endpoint is for obtaining Oozie system status and configuration information.
It supports the following sub-resources: status, os-env, sys-props, configuration, instrumentation, systems, available-timezones .
Identical to the corresponding Oozie v0 WS API
A HTTP GET request returns the system status.
Request:
GET /oozie/v1/admin/status
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{"safeMode":false}
With a HTTP PUT request it is possible to bring in and out hte system from safemode.
Request:
PUT /oozie/v1/admin/status?safemode=true
Response:
HTTP/1.1 200 OK
Identical to the corresponding Oozie v0 WS API
A HTTP GET request returns the Oozie system OS environment.
Request:
GET /oozie/v1/admin/os-env
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{
TERM: "xterm",
JAVA_HOME: "/usr/java/latest",
XCURSOR_SIZE: "",
SSH_CLIENT: "::ffff:127.0.0.1 49082 22",
XCURSOR_THEME: "default",
INPUTRC: "/etc/inputrc",
HISTSIZE: "1000",
PATH: "/usr/java/latest/bin"
KDE_FULL_SESSION: "true",
LANG: "en_US.UTF-8",
...
}
Identical to the corresponding Oozie v0 WS API
A HTTP GET request returns the Oozie Java system properties.
Request:
GET /oozie/v1/admin/java-sys-properties
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{
java.vm.version: "11.0-b15",
sun.jnu.encoding: "UTF-8",
java.vendor.url: "http://java.sun.com/",
java.vm.info: "mixed mode",
...
}
Identical to the corresponding Oozie v0 WS API
A HTTP GET request returns the Oozie system configuration.
Request:
GET /oozie/v1/admin/configuration
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{
oozie.service.SchedulerService.threads: "5",
oozie.service.ActionService.executor.classes: "
org.apache.oozie.dag.action.decision.DecisionActionExecutor,
org.apache.oozie.dag.action.hadoop.HadoopActionExecutor,
org.apache.oozie.dag.action.hadoop.FsActionExecutor
",
oozie.service.CallableQueueService.threads.min: "10",
oozie.service.DBLiteWorkflowStoreService.oozie.autoinstall: "true",
...
}
Identical to the corresponding Oozie v0 WS API
A HTTP GET request returns the Oozie instrumentation information.
Request:
GET /oozie/v1/admin/instrumentation
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{
timers: [
{
group: "db",
data: [
{
ownMinTime: 2,
ownTimeStdDev: 0,
totalTimeStdDev: 0,
ownTimeAvg: 3,
ticks: 117,
name: "update-workflow",
ownMaxTime: 32,
totalMinTime: 2,
totalMaxTime: 32,
totalTimeAvg: 3
},
...
]
},
...
],
samplers: [
{
group: "callablequeue",
data: [
{
name: "threads.active",
value: 1.8333333333333333
},
{
name: "delayed.queue.size",
value: 0
},
{
name: "queue.size",
value: 0
}
]
},
...
],
variables: [
{
group: "jvm",
data: [
{
name: "max.memory",
value: 506920960
},
{
name: "total.memory",
value: 56492032
},
{
name: "free.memory",
value: 45776800
}
]
},
...
]
}
Identical to the corresponding Oozie v0 WS API
A HTTP GET request returns the Oozie build version.
Request:
GET /oozie/v1/admin/build-version
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{buildVersion: "3.0.0-SNAPSHOT" }
A HTTP GET request returns the available time zones.
Request:
GET /oozie/v1/admin/available-timezones
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{
"available-timezones":[
{
"timezoneDisplayName":"SST (Pacific\/Midway)",
"timezoneId":"Pacific\/Midway"
},
{
"timezoneDisplayName":"NUT (Pacific\/Niue)",
"timezoneId":"Pacific\/Niue"
},
{
"timezoneDisplayName":"SST (Pacific\/Pago_Pago)",
"timezoneId":"Pacific\/Pago_Pago"
},
{
"timezoneDisplayName":"SST (Pacific\/Samoa)",
"timezoneId":"Pacific\/Samoa"
},
{
"timezoneDisplayName":"SST (US\/Samoa)",
"timezoneId":"US\/Samoa"
},
{
"timezoneDisplayName":"HAST (America\/Adak)",
"timezoneId":"America\/Adak"
},
{
"timezoneDisplayName":"HAST (America\/Atka)",
"timezoneId":"America\/Atka"
},
{
"timezoneDisplayName":"HST (HST)",
"timezoneId":"HST"
},
...
]
}
Modified in Oozie v1 WS API
These endpoints is for submitting, managing and retrieving information of workflow and coordinator jobs.
A HTTP POST request with an XML configuration as payload creates a job.
The type of job is determined by the presence of one of the following 3 properties:
Or, if none of those are present, the jobtype parameter determines the type of job to run. It can either be mapreduce or pig.
Request:
POST /oozie/v1/jobs
Content-Type: application/xml;charset=UTF-8
.
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<property>
<name>user.name</name>
<value>bansalm</value>
</property>
<property>
<name>oozie.wf.application.path</name>
<value>hdfs://foo:9000/user/bansalm/myapp/</value>
</property>
...
</configuration>
Response:
HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
.
{
id: "job-3"
}
A created job will be in PREP status. If the query string parameter 'action=start' is provided in the POST URL, the job will be started immediately and its status will be RUNNING .
Coordinator jobs with start time in the future they will not create any action until the start time happens.
A coordinator job will remain in PREP status until it's triggered, in which case it will change to RUNNING status. The 'action=start' parameter is not valid for coordinator jobs.
A HTTP PUT request starts, suspends, resumes or kills a job.
Request:
PUT /oozie/v1/job/job-3?action=start
Response:
HTTP/1.1 200 OK
Valid values for the 'action' parameter are 'start', 'suspend', 'resume' and 'kill' and 'rerun'.
A workflow job in SUCCEEDED , KILLED or FAILED status can be partially rerun specifying a list of workflow nodes to skip during the rerun. All the nodes in the skip list must have complete its execution.
The rerun job will have the same job ID.
A rerun request is done with a HTTP PUT request with a rerun action.
Request:
PUT /oozie/v1/job/job-3?action=rerun
Content-Type: application/xml;charset=UTF-8
.
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<property>
<name>user.name</name>
<value>tucu</value>
</property>
<property>
<name>oozie.wf.application.path</name>
<value>hdfs://foo:9000/user/tucu/myapp/</value>
</property>
<property>
<name>oozie.wf.rerun.skip.nodes</name>
<value>firstAction,secondAction</value>
</property>
...
</configuration>
Response:
HTTP/1.1 200 OK
A coordinator job in RUNNING SUCCEEDED , KILLED or FAILED status can be partially rerun by specifying the coordinator actions to re-execute. The actions to execute can be specified in a closed action number range (start-action to end-action) or in a closed datetime range (start-datetime to end-datetime). All the actions to rerun must have run already.
A rerun request is done with a HTTP PUT request with a rerun action and type of rerun.
The type of rerun can be exact or current .
An exact rerun will take the action XML resolved for the previous run (with all latest and version instances fixed) and it will run using the exact same dataset instances for everything.
A current rerun will take the action XML resolved for the action creation and it will resolve to the current values.
Request:
PUT /oozie/v1/job/job-3?action=rerun&type=exact&start-action=4&end-action=10 .
or
PUT /oozie/v1/job/job-3?action=rerun&type=current&start-time=2009-02-01T00:10Z&end-time=2009-03-01T00:10Z .
Response:
HTTP/1.1 200 OK
A HTTP GET request retrieves the job information.
Request:
GET /oozie/v1/job/job-3?show=info&timezone=GMT
Response for a workflow job:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{
**jobType: "workflow",
id: "0-200905191240-oozie-W",
appName: "indexer-workflow",
appPath: "hdfs://user/bansalm/indexer.wf",
externalId: "0-200905191230-oozie-pepe",
user: "bansalm",
group: "other",
status: "RUNNING",
conf: "<configuration> ... </configuration>",
createdTime: "Thu, 01 Jan 2009 00:00:00 GMT",
startTime: "Fri, 02 Jan 2009 00:00:00 GMT",
endTime: null,
run: 0,
actions: [
{
id: "0-200905191240-oozie-W@indexer",
name: "indexer",
type: "map-reduce",
conf: "<configuration> ...</configuration>",
startTime: "Thu, 01 Jan 2009 00:00:00 GMT",
endTime: "Fri, 02 Jan 2009 00:00:00 GMT",
status: "OK",
externalId: "job-123-200903101010",
externalStatus: "SUCCEEDED",
trackerUri: "foo:9001",
consoleUrl: "http://foo:50040/jobdetailshistory.jsp?jobId=...",
transition: "reporter",
data: null,
errorCode: null,
errorMessage: null,
retries: 0
},
...
]
}
Response for a coordinator job:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{
jobType: "coordinator",
id: "0-200905191240-oozie-C",
appName: "indexer-Coord",
appPath: "hdfs://user/bansalm/myapp/logprocessor-coord.xml",
externalId: "0-200905191230-oozie-pepe",
user: "bansalm",
group: "other",
status: "RUNNING",
conf: "<configuration> ... </configuration>",
createdTime: "Thu, 01 Jan 2009 00:00:00 GMT",
startTime: "Fri, 02 Jan 2009 00:00:00 GMT",
endTime: "Fri, 31 Dec 2009 00:00:00 GMT",
frequency: "${days(1)}"
...
**************TBD********************
}
Response for a bundle job:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{
jobType: "bundle",
id: "0-200905191240-oozie-B",
appName: "new-bundle",
appPath: "hdfs://user/bansalm/myapp/logprocessor-bundle.xml",
externalId: "0-200905191230-oozie-pepe",
user: "bansalm",
group: "other",
status: "RUNNING",
conf: "<configuration> ... </configuration>",
createdTime: "Thu, 01 Jan 2009 00:00:00 GMT",
startTime: "Fri, 02 Jan 2009 00:00:00 GMT",
endTime: "Fri, 31 Dec 2009 00:00:00 GMT"
...
**************TBD********************
}
A HTTP GET request retrieves the workflow or a coordinator job definition file.
Request:
GET /oozie/v1/job/job-3?show=definition
Response for a workflow job:
HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8
.
<?xml version="1.0" encoding="UTF-8"?>
<workflow-app name='xyz-app' xmlns="uri:oozie:workflow:0.1">
<start to='firstaction' />
...
<end name='end' />
</workflow-app>
Response for a coordinator job:
HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8
.
<?xml version="1.0" encoding="UTF-8"?>
<coordinator-app name='abc-app' xmlns="uri:oozie:coordinator:0.1" frequency="${days(1)}
start="2009-01-01T00:00Z" end="2009-12-31T00:00Z" timezone="America/Los_Angeles">
<datasets>
...
</datasets>
...
</cordinator-app>
Response for a bundle job:
HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8
.
<?xml version="1.0" encoding="UTF-8"?>
<bundle-app name='abc-app' xmlns="uri:oozie:coordinator:0.1"
start="2009-01-01T00:00Z" end="2009-12-31T00:00Z"">
<datasets>
...
</datasets>
...
</bundle-app>
An HTTP GET request retrieves the job log.
Request:
GET /oozie/v1/job/job-3?show=log
Response:
HTTP/1.1 200 OK Content-Type: text/plain;charset=UTF-8 . ... 23:21:31,272 TRACE oozieapp:526 - USER[bansalm] GROUP[other] TOKEN[-] APP[test-wf] JOB[0-20090518232130-oozie-tucu] ACTION[mr-1] Start 23:21:31,305 TRACE oozieapp:526 - USER[bansalm] GROUP[other] TOKEN[-] APP[test-wf] JOB[0-20090518232130-oozie-tucu] ACTION[mr-1] End ...
An HTTP GET request returns the image of the workflow DAG (rendered as a PNG image).
Request:
GET /oozie/v1/job/job-3?show=graph[&show-kill=true]
Response:
HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: {image_size_in_bytes}{image_bits}
The optional show-kill parameter shows kill node in the graph. Valid values for this parameter are 1 , yes , and true . This parameter has no effect when workflow fails and the failure node leads to the kill node; in that case kill node is shown always.
The node labels are the node names provided in the workflow XML.
This API returns HTTP 400 when run on a resource other than a workflow, viz. bundle and coordinator.
A HTTP GET request retrieves workflow and coordinator jobs information.
Request:
GET /oozie/v1/jobs?filter=user%3Dbansalm&offset=1&len=50&timezone=GMT
Note that the filter is URL encoded, its decoded value is user=tucu .
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{
offset: 1,
len: 50,
total: 1002,
**jobs: [
{
** jobType: "workflow"
id: "0-200905191240-oozie-W",
appName: "indexer-workflow",
appPath: "hdfs://user/tucu/indexer-wf",
user: "bansalm",
group: "other",
status: "RUNNING",
createdTime: "Thu, 01 Jan 2009 00:00:00 GMT",
startTime: "Fri, 02 Jan 2009 00:00:00 GMT",
endTime: null,
info: "run=0",
},
{
** jobType: "coordinator"
id: "0-200905191240-oozie-C",
appName: "logprocessor-coord",
appPath: "hdfs://user/bansalm/myapp/logprocessor-coord.xml",
user: "bansalm",
group: "other",
status: "RUNNING",
createdTime: "Thu, 01 Jan 2009 00:00:00 GMT",
startTime: "Fri, 02 Jan 2009 00:00:00 GMT",
endTime: "Fri, 31 Dec 2009 00:00:00 GMT",
info: "nextAction=5",
},
{
** jobType: "bindle"
id: "0-200905191240-oozie-B",
appName: "logprocessor-bundle",
appPath: "hdfs://user/bansalm/myapp/logprocessor-bundle.xml",
user: "bansalm",
group: "other",
status: "RUNNING",
createdTime: "Thu, 01 Jan 2009 00:00:00 GMT",
startTime: "Fri, 02 Jan 2009 00:00:00 GMT",
endTime: "Fri, 31 Dec 2009 00:00:00 GMT",
},
...
]
}
No action information is returned when querying for multiple jobs.
The syntax for the filter is
[NAME=VALUE][;NAME=VALUE]*
Valid filter names are:
The query will do an AND among all the filter names.
The query will do an OR among all the filter values for the same name. Multiple values must be specified as different name value pairs.
Additionally the start and len parameters can be used for pagination. The start parameter is base 1. Moreover, the jobtype parameter could be used to determine what type of job is looking for. The valid values of job type are: workflow , coordinator or bundle .
A HTTP GET request retrieves a bulk response for all actions, corresponding to a particular bundle, that satisfy user specified criteria. This is useful for monitoring purposes, where user can find out about the status of downstream jobs with a single bulk request. The criteria are used for filtering the actions returned. Valid options (_case insensitive_) for these request criteria are:
Specifying 'bundle' is REQUIRED. All the rest are OPTIONAL but that might result in thousands of results depending on the size of your job. (pagination comes into play then)
If no 'actionStatus' values provided, by default KILLED,FAILED will be used. For e.g if the query string is only "bundle=MyBundle", the response will have all actions (across all coordinators) whose status is KILLED or FAILED
The query will do an AND among all the filter names, and OR among each filter name's values.
The syntax for the request criteria is
[NAME=VALUE][;NAME=VALUE]*
For 'coordinators' and 'actionStatus', if user wants to check for multiple values, they can be passed in a comma-separated manner. *Note*: The query will do an OR among them. Hence no need to repeat the criteria name
All the time values should be specified in ISO8601 (UTC) format i.e. yyyy-MM-dd'T'HH:mm'Z'
Additionally the offset and len parameters can be used as usual for pagination. The start parameter is base 1.
If you specify a coordinator in the list, that does not exist, no error is thrown; simply the response will be empty or pertaining to the other valid coordinators. However, if bundle name provided does not exist, an error is thrown.
Request:
GET /oozie/v1/jobs?bulk=bundle%3Dmy-bundle-app;coordinators%3Dmy-coord-1,my-coord-5;actionStatus%3DKILLED&offset=1&len=50
Note that the filter is URL encoded, its decoded value is user=chitnis . If typing in browser URL, one can type decoded value itself i.e. using '='
Response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
.
{
offset: 1,
len: 50,
total: 1002,
** bulkresponses: [
** {
bulkbundle:
{
bundleJobName: "my-bundle-app",
bundleJobId: "0-200905191240-oozie-B",
status: "SUSPENDED",
},
bulkcoord:
{
coordJobName: "my-coord-1",
status: "SUSPENDED",
},
bulkaction:
{
id: "0-200905191240-oozie-C@21",
coordJobId: "0-200905191240-oozie-C",
actionNumber: 21,
externalId: "job_00076_0009",
status: "KILLED",
externalStatus: "FAILED",
errorCode: "E0902",
errorMessage: "Input file corrupt",
createdTime: "Fri, 02 Jan 2009 00:00:00 GMT",
nominalTime: "Thu, 01 Jan 2009 00:00:00 GMT",
missingDependencies: "hdfs://nn:port/user/joe/file.txt"
},
},
** {
bulkbundle:
{
bundleJobName: "my-bundle-app",
bundleJobId: "0-200905191240-oozie-B",
status: "SUSPENDED",
}
bulkcoord:
{
coordJobName: "my-coord-5",
status: "SUSPENDED",
}
bulkaction:
{
id: "0-200905191245-oozie-C@114",
coordJobId: "0-200905191245-oozie-C",
actionNumber: 114,
externalId: "job_00076_0265",
status: "KILLED",
externalStatus: "KILLED",
errorCode: "E0603",
errorMessage: "SQL error in operation ...",
createdTime: "Fri, 02 Jan 2009 00:00:00 GMT",
nominalTime: "Thu, 01 Jan 2009 00:00:00 GMT",
missingDependencies:
}
}
...
]
}