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 |
|
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 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. Here, the system will attempt 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 subsequently issue the service described in Obtain the status of a job. Asynchronous processing is the default for all z/OS jobs REST interface services.
- 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 be set up and active on your z/OS system. For information, see 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 be authorized to run jobs on the system and be able to access any protected resources that the job might require.
- READ access to <SAF_PREFIX> in the APPL class
- READ access to the <SAF_PREFIX>.izuUsers profile 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 z/OS Security Server RACF Security Administrator's Guide.
If run asynchronously, these services also require that your user ID be 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 the chapter on CIM server quick setup and verification in z/OS Common Information Model User's Guide, SC33-7998.
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 when submitted jobs complete. 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 the job ends, z/OSMF returns an HTTP message to the URL location, indicating the job completion status. The data returned is in the form of a JSON document.
The asynchronous job notifications function is available for JES2 systems only; it is not available for JES3 systems.
The key requirement is that you must create a subscription to the Common Information Model (CIM) jobs indication provider for your system. Also, if the job notifications will require a secure network connection, you must enable an SSL connection between the client application and the server, including the sharing of digital certificates. For instructions on enabling the asynchronous job notifications function, see 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 login 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 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 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