z/OS data set and file REST interface

The z/OS data set and file REST interface is an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. A set of REST services is provided for working with data sets and UNIX files on a z/OS system.

The z/OS data set and file REST interface services provide a programming interface for working with z/OS data sets and UNIX files. This function is similar to using GET and PUT requests through file transfer protocol (FTP), but secured through traditional z/OS security controls for user authentication and resource authorizations. For setup details, see Required authorizations.

Table 1 lists the operations that the z/OS data set and file REST interface services provide.

Table 1. Operations provided through the z/OS data set and file REST interface services.
Operation	HTTP method and URI path
List the z/OS data sets on a system	GET /zosmf/restfiles/ds?dslevel=`<dataset_name_pattern>`[&volser=`<volser>&start=<dsname>`]
List the members of a z/OS data set	GET /zosmf/restfiles/ds/`<dataset_name>`/member?start=<member>&pattern=<mem-pat>
Retrieve the contents of a z/OS data set or member	GET /zosmf/restfiles/ds/[-(`<volser>`)/]`<data-set-name>`[(`<member-name>`)]
Write data to a z/OS data set or member	PUT /zosmf/restfiles/ds/[-(`<volser>`)/]`<data-set-name>`[(`<member-name>`)]
Create a sequential and partitioned data set	POST /zosmf/restfiles/ds/`<data-set-name>`
Delete a sequential and partitioned data set	DELETE /zosmf/restfiles/ds/`<data-set-name>` DELETE /zosmf/restfiles/ds/-`(<volume>)/<data-set-name>`
Delete a partitioned data set member	DELETE /zosmf/restfiles/ds/`<dataset-name>(<member-name>)`
z/OS Data set and member utilities	PUT /zosmf/restfiles/ds/`<to-data-set-name>`
Access Method Services Interface	PUT /zosmf/restfiles/ams
List the files and directories of a UNIX file path	GET /zosmf/restfiles/fs?path=`<file-path-name>`
Retrieve the contents of a z/OS UNIX file	GET /zosmf/restfiles/fs/`<file-path-name>`
Write data to a z/OS UNIX file	PUT /zosmf/restfiles/fs/`<filepath-name>`
Create a UNIX file or directory	POST /zosmf/restfiles/fs/`<file-path-name>`
Delete a UNIX file or directory	DELETE /zosmf/restfiles/fs/`<file-pathname>`
z/OS UNIX file utilities	PUT /zosmf/restfiles/fs/`<file-path-name>`
List z/OS UNIX Filesystems	GET /zosmf/restfiles/mfs/
Create z/OS UNIX zFS Filesystem	POST /zosmf/restfiles/mfs/zfs/`<file-system-name>`
Delete z/OS UNIX zFS Filesystem	DELETE /zosmf/restfiles/mfs/zfs/`<file-system-name>`
Mount a UNIX file system	PUT /zosmf/restfiles/mfs/`<file-system-name>`
Unmount a UNIX file system	PUT /zosmf/restfiles/mfs/`<file-system-name>`

Using the Swagger interface

You can use the Swagger interface to display information about the z/OS data sets and files REST APIs. The Swagger interface includes four sections: AMS APIs, Dataset APIs, File APIs, and Filesystem APIs. For more information, see Using the Swagger interface.

Processing overview

The z/OS data set and file REST interface services can be invoked by any client application, running on the local z/OS system or a remote system. Your program (the client) initiates a request to the server through a standard HTTP request method, such as GET or PUT. If the server determines that the request is valid, it performs the requested service and returns an HTTP response to your program.

For a successful request, this response takes the form of an HTTP 2nn status code and, if applicable, a result set that is passed back to your program. Depending on which service is requested, the result set might be returned in a format that requires parsing by your program, such as a JSON object. In other cases, the results might be returned in another format, such as plain text or binary data.

For an unsuccessful request, the server response consists of a non-OK HTTP response code and details of the error, which are provided in the form of a JSON object.

The contents of the JSON objects are described in JSON document specifications for z/OS data set and file REST interface requests.

Note:

If the URL contains a resolved character such as # $ @, it must be URL-encoded, so that it can be escaped.
For example:
GET /zosmf/restfiles/ds/SYS1.PROCLIB(#ABC) HTTP/1.1
Should be changed to:
GET /zosmf/restfiles/ds/SYS1.PROCLIB(%23ABC) HTTP/1.1

Common HTTP Request Headers

X-IBM-Async-Threshold = <nnn>

This header can be added to a request to enable support for asynchronous responses with the HTTP status code 202 Accepted. This specifies the number of seconds that the client wishes to wait for a response before receiving a 202 Accepted response. This response includes a Location response header with the URL (excluding protocol, host, and port) that can be used with a subsequent GET method request to obtain the results from the original request. Each subsequent request includes its own X-IBM-Async-Threshold header if additional async responses are required. The value of this header must be an integer 0 - 60 seconds. A value of 0 indicates that an async response is returned if the actual response is not immediately available. If X-IBM-Async-Threshold is specified, then X-IBM-Response-Timeout does not apply and is ignored. A DELETE method request can also be sent to the URL returned in an asynchronous response to abandon the original request and terminate the associated CEA TSO address space.

Example of an Asynchronous request

Request:

GET  /zosmf/restfiles/ds?dslevel=D10 HTTP/1.1
X-IBM-Async-Threshold: 3

Response:

202 Accepted
X-Powered-By:  Servlet/3.0
Location:  /zosmf/restfiles/queue/FS11fae7
X-IBM-Txid:  tx000000000000D159
Content-Language:  en-US
Content-Length:  0
Date:  Fri, 18 Nov 2016 07:17:21 GMT

Request:

GET  GET /zosmf/restfiles/queue/FS11fae7 HTTP/1.1 HTTP/1.1
X-IBM-Async-Threshold: 3

Response:

200 OK
Content-Type:  application/json; charset=UTF-8
Content-Length:  39199
X-IBM-Txid:  tx000000000000D160
Date:  Fri, 18 Nov 2016 07:18:32 GMT
{"items":[
  {"dsname":"D10"},
  {"dsname":"D10.$DATA.SETS"},
  {"dsname":"D10.AAAAA"},
  {"dsname":"D10.AACTIVE.JCL"},
  {"dsname":"D10.AA11797.R1K.D050701A"},
  {"dsname":"D10.AA12484.HDZ11K0"},
  {"dsname":"D10.AA12484.HDZ11K0.TRSD"},
  {"dsname":"D10.ABACKUP.SM02631.FPGA.D14163.T131433"},
  {"dsname":"D10.ABARS1.C.C01V0001"},

X-IBM-Response-Timeout = <nnn>

This specifies the number of seconds that a TsoServlet request runs before a timeout occurs and an exception is returned to the client. This time does not include the time that can be required to start a new CEATSO address space. The default is 30 seconds, and the allowed range for this value is 5 - 600 seconds. An invalid value that is supplied for this header is converted into the closest valid value and the request proceeds.

Note: This timeout does not affect any timeouts that may occur in the z/OSMF Websphere container or the REST service client.

Common HTTP Response Headers

X-IBM-Txid = <string>: This header returns the transaction id that was assigned by z/OSMF to the request. It can be useful for diagnostic purposes to identify z/OSMF log records relating to a failed transaction. This txid will also be logged in the TSO address space. It should not be used for other purposes; its format can change; and it might not be present in future releases.

Specifying an entity tag with your read and write requests

During request processing, your program’s access to the resource (a data set or file) is serialized by z/OS. No other users can read the resource or write to it, thus preventing concurrent updates of the resource from overwriting each other. Serialization, however, ends with the completion of the request. If your program must perform multiple read and write requests on a resource, you require a method of ensuring that the resource is not modified between your program’s requests. Otherwise, you might overlay another user’s changes.

To help you to ensure the integrity of a resource between requests, the z/OS data set and file REST interface supports the use of an entity tag (or ETag) on your requests. Obtained on the initial read (GET) request, the ETag is an identifier that is assigned by the web server to a specific version of the resource. If the resource content changes, a new ETag is associated with the resource.

To determine whether a resource was changed between requests, your program supplies its ETag as a header value on each request. If the ETag matches the current ETag for the resource, the system considers the resource to be unchanged and performs the request. Otherwise, the system fails the request; your program must obtain the ETag again before it can perform the request.

Generally, the process of updating the contents of a z/OS data set or UNIX file is as follows:

Retrieve the current content of the resource by using a GET request.
The server returns the contents of the resource in the response body as plain text, along with information about the resource, in the response headers:
- Content-Length header specifies the length of the data that was returned
- ETag header specifies the ETag that identifies the current version of the resource.
Replace the contents of the resource by using a PUT request. The request includes the following headers:
- A request header to supply the ETag that was returned from the previous GET request on that resource. If the token still matches, the resource was not changed since the previous GET request. If the supplied token does not match a currently valid token, the PUT request fails with an HTTP 412. This response indicates that the host system file was modified in the time since the read operation was performed.
- Optionally, a request header to specify whether data conversion is required.
For a PUT request, the request body contains the new contents of the file.

After the data is written, the 204 No Content response is returned with a new ETag, for use with any subsequent read or write requests.

Suppose you only want to replace a resource with a new copy, without first reading the contents of the current resource. To overlay the resource, have your program issue the initial GET request to obtain the ETag. Here, you would specify a maximum read amount of 0. Then, have your program issue a PUT request with the ETag and the new data to be written to the resource.

Content type used for HTTP request and response data

The JSON content type ("Content-Type: application/json") is used for request and response data. For the detailed format of each JSON object, see JSON document specifications for z/OS data set and file REST interface requests.

Required installation

To enable the z/OS data set and file REST interface services, IBM supplies a default procedure in your z/OSMF order, which you must install before you configure z/OSMF. 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 data set and file REST interface services as when you perform these operations through a TSO/E session on the system. For example, listing the members of a z/OS data set through the z/OS data set and file REST interface requires authorization to start TSO on the system and access to the specified data set.

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 <IZU_SAF_PROFILE_PREFIX> in the APPL class.
READ access to the <IZU_SAF_PROFILE_PREFIX>.*.izuUsers profile in the EJBROLE class.

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

Where applicable, further authorization requirements are noted in the descriptions of the individual z/OS data set and file REST interface services.

For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

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 error 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: Request was processed successfully.
HTTP 204 No content: Request was processed successfully, however, no content was returned. This status is normal for some types of requests, such as when no data sets or files match the filter criteria, or the specified partitioned data set has no members.
HTTP 206 Partial content: Request was processed successfully, however, only a portion of the available content was received. The request contained the X-IBM-Max-Items header, which limited the amount of content that was returned.
HTTP 304 Not Modified: An ETag token was included in the request. z/OSMF determined that the requested resource did not change since the ETag token was created.
HTTP 400 Bad request: Request could not be processed because it contains a syntax error or an incorrect parameter.
HTTP 401 Unauthorized: Request could not be processed because the client is not authorized. This status is returned if the request contained an incorrect user ID or password, or both, or the client did not authenticate to z/OSMF.
HTTP 404 Not found: Requested resource does not exist.
HTTP 405 Method not allowed: Requested resource is a valid resource, but an incorrect method was used to submit the request. For example, the request used the POST method when the GET method was expected.
HTTP 412 Precondition failed: The supplied ETag token indicated that the resource was modified since the token was created. Therefore, the request failed the If-Match precondition that was specified in the header.
HTTP 413 Request entity too large: The supplied data is too large to process. Or, the requested resource is too large to return.
HTTP 429 Too many requests: The client submitted too many unsuccessful login attempts.
HTTP 500 Internal server error: Server encountered an error. See the response body for a JSON object with information about the error.
HTTP 503 Service unavailable: Server is not available.

Error logging

Errors from the z/OS data set and file 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.