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.

Table 1 lists the operations that the z/OS jobs REST interface services provide.
Table 1. Operations provided through the z/OS jobs REST interface services.
Operation HTTP method and URI path
Obtain the status of a job
  • GET /zosmf/restjobs/jobs/<jobname>/<jobid>?[step-data=Y|N]
  • GET /zosmf/restjobs/jobs/<correlator>?[step-data=Y|N]
List the jobs for an owner, prefix, or job ID
  • GET /zosmf/restjobs/jobs[?<parms>]
List the spool files for a job
  • GET /zosmf/restjobs/jobs/<jobname>/<jobid>/files
  • GET /zosmf/restjobs/jobs/<correlator>/files
Retrieve the contents of a job spool file
  • GET /zosmf/restjobs/jobs/<jobname>/<jobid>/files/<nnn>/records
  • GET /zosmf/restjobs/jobs/<correlator>/files/<nnn>/records
  • GET /zosmf/restjobs/jobs/<jobname>/<jobid>/files/JCL/records
  • GET /zosmf/restjobs/jobs/<correlator>/files/JCL/records
Submit a job
  • PUT /zosmf/restjobs/jobs[/-<JESB>]
Hold a job
  • PUT /zosmf/restjobs/jobs/<jobname>/<jobid>
  • PUT /zosmf/restjobs/jobs/<correlator>
Release a job
  • PUT /zosmf/restjobs/jobs/<jobname>/<jobid>
  • PUT /zosmf/restjobs/jobs/<correlator>
Change the job class
  • PUT /zosmf/restjobs/jobs/<jobname>/<jobid>
  • PUT /zosmf/restjobs/jobs/<correlator>
Cancel a job
  • PUT /zosmf/restjobs/jobs/<jobname>/<jobid>
  • PUT /zosmf/restjobs/jobs/<correlator>
Cancel a job and purge its output
  • DELETE /zosmf/restjobs/jobs/<jobname>/<jobid>
  • DELETE /zosmf/restjobs/jobs/<correlator>

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

The URLs of the z/OS jobs REST interface have the format that is shown in Figure 1:
Figure 1. Format of resource URLs for z/OS jobs REST interface.
https://{host}:{port}/zosmf/restjobs/jobs/{-jesb/}{resource}?{parm}
Where:
  • "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

The z/OS jobs REST interface provides the following 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

The data that is sent or returned by the HTTP methods has one of the following 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.

The following HTTP status codes are valid:
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

The z/OS jobs REST interface includes services that you can use to perform job modify operations, as shown in Table 2.
Table 2. Job modify operations provided through the z/OS jobs REST interface services.
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 Start of changeor omit the "version" property.End of change 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.

Generally, the differences in processing are as follows:
  • Start of changeFor 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.End of change
  • 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.

In addition, your user ID requires authorization to the z/OSMF SAF profile prefix on the target z/OS system, as follows:
  • READ access to <SAF_PREFIX> in the APPL class
  • READ access to the <SAF_PREFIX>.*.izuUsers profile in the EJBROLE class. Or, at a minimum, READ access to the <SAF_PREFIX>.IzuManagementFacilityRestJobs resource name in the EJBROLE class.

By default, the z/OSMF SAF profile prefix is IZUDFLT.

If you are using z/OS jobs REST interface services to perform job modify operations, your user ID must be authorized to the appropriate resources in the JESJOBS class, as shown in Table 3.
Table 3. JESJOBS class authorizations needed for performing job modify operations
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 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 returned data 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 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 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