z/OS jobs REST interface
The z/OS® jobs REST interface is an application programming interface (API) implemented through industry standard Representational State Transfer (REST) services. A set of REST services is provided for working with batch jobs on a z/OS system, as described in this topic.
| Operation | HTTP method and URI path |
|---|---|
| Obtain the status of a job |
|
| List the jobs for an owner, prefix, or job ID |
|
| List the spool files for a job |
|
| Retrieve the contents of a job spool file |
|
| Submit a job |
|
| Hold a job |
|
| Release a job |
|
| Change the job class |
|
| Cancel a job |
|
| Cancel a job and purge its output |
|
Using the Swagger interface
You can use the Swagger interface to display information about the z/OS jobs REST APIs. The Swagger interface includes one section: Jobs APIs. For more information, see Using the Swagger interface.
Processing overview
The z/OS jobs REST interface services can be invoked by any HTTP client application, running on the z/OS local system or a remote system.
Your program (the client) initiates an HTTP request to the z/OS jobs REST interface. If the interface determines that the request is valid, it performs the requested service. After performing the service, the z/OS jobs REST interface creates an HTTP response. If the request is successful, this response takes the form of an HTTP 2nn response and, if applicable, a result set that is passed back to your program.
Depending on which service was requested, the result set might be returned in a format that requires parsing by your program, for example, a JSON object. In other cases, results might be returned in another format, such as plain text or binary data. If the request is not successful, the response consists of a non-OK HTTP response code with details of the error that is provided in the form of a JSON object. The contents of the JSON objects are described in JSON document specifications for z/OS jobs REST interface requests.
Resource URLs
https://{host}:{port}/zosmf/restjobs/jobs/{-jesb/}{resource}?{parm}"https://{host}:{port}"specifies the target system address and port."/zosmf/restjobs/jobs/"identifies the z/OS jobs REST interface."JESB"optionally specifies a secondary JES subsystem, if one is to be used to process the request. If you omit this value, the request is processed by the primary JES subsystem."{resource}?{parm}"represents the resource, such as a job name and job ID, and optionally one or more parameters, to qualify the request.
HTTP methods
- GET
- Retrieves information about jobs that are running on the z/OS system.
- PUT
- Updates job information on the z/OS system, or sets attributes and performs actions on jobs.
- DELETE
- Removes jobs from the z/OS system.
Some situations might require the use of the POST method; see Usage considerations for the z/OSMF REST services.
Supported HTTP versions
z/OS jobs REST interface supports requests in either of the following protocols: HTTP/1.0 or HTTP/1.1
Content types
- Application/octet-stream (
Content-Type: application/octet-stream) is used for data that is sent or returned in an uninterpreted format, such as a job that is submitted, or binary data or records that are obtained from a z/OS job spool file. - JSON (
Content-Type: application/json) is used for sent data and returned data. For the detailed format of each JSON object, see the description for each operation. - Plain text (
Content-Type: plain/text).
Error handling
For errors that occur during the processing of a request, the API returns an appropriate HTTP
status code to the calling client. An error is indicated by a 4nn code or a
5nn code. For example, HTTP/1.1 400 Bad Request or
HTTP/1.1 500 Internal Server Error.
In addition, some errors might also include a returned JSON object that contains a message that describes the error. You can use this information to diagnose the problem or provide it to IBM® Support, if required. For the contents of the error report document, see Error report document.
- HTTP 200 OK
- Success.
- HTTP 201 Created
- Request was successful, and, as a result, a resource was created.
- HTTP 202 Accepted
- Request was received and accepted for processing, but the processing has not yet completed.
- HTTP 400 Bad request
- Request contained incorrect parameters.
- HTTP 500 Internal server error
- Programming error.
Synchronous support for the job modify operations
| Operation | Where described |
|---|---|
| Hold a job. | Hold a job |
| Release a job. | Release a job |
| Change the job class. | Change the job class |
| Cancel a job. | Cancel a job |
| Delete a job (cancel a job and purge its output). | Cancel a job and purge its output |
These services can be run synchronously if coded to use the latest version of the service. To
request synchronous processing, set the "version" property in your request to 2.0
or omit the "version" property. If so, the system attempts to process the
request synchronously, if such processing is supported on the target JES subsystem. Synchronous
processing is supported for JES2 subsystems only. When the target subsystem is JES3, a synchronous
request is ignored and the service is performed asynchronously.
- For an asynchronous request, z/OSMF returns control to the caller immediately. However, to verify that the initial request was performed, the caller must then issue the service that is described in Obtain the status of a job.
- For a synchronous request, z/OSMF does not return control to the caller until the requested action is performed and results of the request are available to be returned to the caller. Here, the JSON job feedback document provides more information about the success or failure of the request; see Job feedback document.
If your program does not require feedback on the results of requested actions, you can use these services asynchronously.
Due to timing behavior, if you submit a job and immediately issue a synchronous request for the
same job, you might receive the error message "No job found for reference" in the
JSON error report document (category 6, return code 4, reason code 10). To avoid this occurrence, it
is recommended that you allow a small amount of time to pass between a job submit request and a
subsequent job modify request.
Required system setup
The z/OS jobs REST interface services require that the System REXX (SYSREXX) component is set up and active on your z/OS system. For information, see Ensuring that System REXX is set up and active in IBM z/OS Management Facility Configuration Guide.
Required authorizations
Generally, your user ID requires the same authorizations for using the z/OS jobs REST interface services as when you perform these operations through a TSO/E session on the system. For example, submitting a job through the z/OS jobs REST interface requires that your user ID is authorized to run jobs on the system and can access any protected resources that the job might require.
- READ access to
<SAF_PREFIX>in the APPL class - READ access to the
<SAF_PREFIX>.*.izuUsersprofile in the EJBROLE class. Or, at a minimum, READ access to the<SAF_PREFIX>.IzuManagementFacilityRestJobsresource name in the EJBROLE class.
By default, the z/OSMF SAF profile prefix is IZUDFLT.
| Operation | JESJOBS resource | Access required |
|---|---|---|
| Hold a job | HOLD.nodename.userid.jobname | UPDATE |
| Release a job | RELEASE.nodename.userid.jobname | UPDATE |
| Change the job class | MODIFY.nodename.userid.jobname | UPDATE |
| Cancel a job | CANCEL.nodename.userid.jobname | ALTER |
| Delete a job (cancel a job and purge its output) | CANCEL.nodename.userid.jobname | ALTER |
For more information about JESJOBS class, see Controlling the use of job names in z/OS Security Server RACF® Security Administrator's Guide.
If run asynchronously, these services also require that your user ID is authorized to the Common Information Model (CIM) server and permitted to the JES2-JES3Jobs CIM provider. CIM includes jobs (CFZSEC and CFZRCUST) to help you configure the CIM server, including security authorizations and file system customization. For information, see Quick guide: CIM server setup and verification in z/OS Common Information Model User's Guide.
Where applicable, additional authorization requirements are noted in the descriptions of the individual z/OS jobs REST interface services. For information about client authentication in z/OSMF, see Authenticating to z/OSMF.
Requesting asynchronous job notifications
You can use the asynchronous job notifications function of z/OSMF to allow your
programs to be notified of job events.
The asynchronous job notifications function is available for JES2 systems only; it is not available for JES3 systems.
There are two mechanisms to support asynchronous job
notifications: - JES2 EDS for job notifications over HTTP
- Common Information Model (CIM) jobs indication provider
With this function, the program that submits the job through
the z/OS jobs REST interface services PUT method specifies a URL when submitting the job. When using
JES2 EDS, you can define the events of a submitted job, and if any of those events happen, z/OSMF
returns an HTTP message to the URL location. When using CIM, z/OSMF returns an HTTP
message to the URL location only when a job ends, indicating the job completion status. The
data returned is in the form of a JSON document.
You only need to configure one of the mechanisms and it is
recommended you use JES2 EDS for job notifications over HTTP.
For instructions on enabling the asynchronous job notifications
function, see Configuring your system for asynchronous job notifications in IBM z/OS Management Facility Configuration Guide.
Enabling browser login through a client certificate
It is possible to run the z/OS jobs REST interface services directly from a web browser. Here, you must first authenticate to z/OSMF through your browser. In z/OSMF authentication is typically done by entering your user ID and password at the Welcome page. However, it is also possible to log in with a client certificate, if your installation favors this approach. With a client certificate, you can access z/OSMF through your browser without having to supply a user ID and password.
In client certificate authentication, the certificate is stored in the browser itself. When you log in to z/OSMF, the server requests the certificate from your browser. If your browser stores more than one certificate, you might be prompted to select the correct one to use with z/OSMF. Otherwise, your browser sends the certificate to z/OSMF. After z/OSMF identifies you as the owner of the key that is associated with the certificate, a secure connection is established.
If z/OSMF does not accept your client certificate, z/OSMF displays the Welcome page for you to enter your user ID and password.
If your installation plans to enable client certificate login for the z/OS jobs REST interface services, understand that it is your responsibility to create the certificate and manage its distribution to users. It is recommended that you ensure that users have browsers that support importing a certificate.
For information about creating digital certificates, see RACF and digital certificates in z/OS Security Server RACF Security Administrator's Guide.
Error logging
Errors from the z/OS jobs REST interface services are logged in the z/OSMF log. You can use this information to diagnose the problem or provide it to IBM Support, if required. For information about working with z/OSMF log files, see z/OSMF log files in IBM z/OS Management Facility Configuration Guide.
Enabling traces for IBM analysis
For diagnostic purposes, your installation might be asked by IBM Support to enable tracing for the z/OS jobs REST interface. For information, see Enabling tracing for the z/OS jobs REST interface