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.
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.
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 a202 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:
Response:GET /zosmf/restfiles/ds?dslevel=D10 HTTP/1.1 X-IBM-Async-Threshold: 3
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
- 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.
- 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. - 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
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.
- 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.
- 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.