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.
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.
Example operations
Operations provided through the z/OS data set and file REST interface services example:
|
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>]
|
|
Write data to a z/OS UNIX file
|
PUT /zosmf/restfiles/fs/<filepath-name>
|
|
List z/OS UNIX Filesystems
|
GET /zosmf/restfiles/mfs/
|
|
Mount a UNIX file system
|
PUT /zosmf/restfiles/mfs/<file-system-name>
|
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.
In the following example, the GET method is used to list all of the cataloged data sets that match the partial name IBMUSER.CONFIG.*.
Example request
GET /zosmf/restfiles/ds?dslevel=IBMUSER.CONFIG.* HTTP/1.1
where:
- /zosmf/restfiles specifies the z/OS data set and file REST interface
- /ds indicates a data set request
- ?dslevel=<dataset-name-pattern>[&volser=<volser>&start=<dsname>] represents the query parameters used to qualify the request, such as a data set name and, optionally, a volume serial (VOLSER).
Example response
A sample response is shown below:
Response:
200 OK
x-powered-by: Servlet/3.0
Content-Type: application/json; charset=UTF-8
Content-Length: 201
Content-Language: en-US
Date: Mon, 23 Nov 2015 09:10:11 GMT
Response Body:
{"items":[{"dsname":"IBMUSER.CONFIG.FS"},{"dsname":"IBMUSER.CONFIG.FS.DATA"},{"dsname":"IBMUSER.CONFIG.ORIG.FS"},{"dsname":"IBMUSER.CONFIG.ORIG.FS.DATA"}],"returnedRows":4,"JSONversion":1}
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.
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.
References:
1. z/OS Management Facility Programming Guide:
https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.izua700/IZUHPINFO_API_RESTFILES.htm
2. z/OSMF Marketplace:
https://www.ibm.com/us-en/marketplace/zos-management-facility
3. z/OSMF Trail：
https://www.ibm.com/account/reg/us-en/signup?formid=urx-34578
4. z/OSMF One Stop Hub:
https://www.ibm.com/developerworks/community/blogs/e0c474f8-3aad-4f01-8bca-f2c12b576ac9/entry/z_OSMF_One_Stop_Hub?lang=en