Using the z/OSMF REST services
z/OSMF supports the use of Representational State Transfer (REST) APIs, which are public APIs that your application can use to work with system resources and extract system data. As with implementations of REST services on other platforms, the z/OSMF APIs allow for easy-to-use services that are language- and platform-independent, stateless, scalable, and easily parsed.
Processing overview
The z/OSMF REST services can be invoked by any hypertext transfer protocol (HTTP) client application, running on the z/OS® local system or a remote system. The services support requests in either of the following protocols: HTTP/1.0 or HTTP/1.1.
Conceptually, your application (the client) issues requests to the target system (z/OS) in the form of request messages. The product name is z/OS. Each request message consists of a request line, optionally followed by request headers (HTTP headers), an empty line, and an optional message body. The request line includes the HTTP method, such as GET, a Universal Resource Locator (URL) and, where appropriate, parameters that further qualify the request. The URL is required and must be URI-encoded as specified in RFC 2396. For more information about RFC 2396, see the Uniform Resource Identifiers (URI): Generic Syntax web page.
If the API determines that the request is valid, it performs the requested service. After performing the service, the API creates an HTTP response. If the request is successful, this response takes the form of an HTTP 200 (OK) response and, if applicable, an object that contains a result set. Depending on which service was requested, the result set might be returned in a format that requires parsing by your program, for example, a JavaScript Object Notation (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.
- Hypertext Transfer Protocol 1.1: http://www.w3.org/Protocols/
- Multipurpose Internet Mail Extensions (MIME) media types: http://www.iana.org/assignments/media-types/index.html
- Introducing JSON: http://www.json.org.
Authenticating to z/OSMF
Your client program must authenticate to z/OSMF on the target z/OS system. Typically, authentication is done through the HTTP header included in each client request, which is referred to as a stateless technique.
- On the first request to the server, the client request includes a basic HTTP authentication
header that contains a valid user ID and password. The header property value pair should look like
this:
where <encoding of userid:password> is a base 64 encoding of <userid>:<password>.'Authorization':'Basic <encoding of userid:password>' - On successful log-in, your application receives the following values in the response header:
- HTTP status code 200
- Lightweight Third Party Access (LTPA) token, which contains the credentials for your application. In the case of z/OSMF, the token is a LtpaToken2 value, which supports strong encryption.
- On subsequent requests, your application supplies the LTPA token for authentication with z/OSMF instead of the basic HTTP authorization header.
You can provide the LTPA token through the Cookie header property, for example:
followed by the token, for example:'Cookie':'<ltpaToken2=<tokenvalue>''Cookie': 'LtpaToken2=IExabotu2sfNbJij6rajHJcFiDi 1H0hml3yKvylwfJ4q8goCFEYH41FQNlAgdMMVP6/nVbH/IKw 0l5b7ZqWuZ8ndOYcECAJg1ss2Vq4q21C1jLvVGTyNLk6rvbgs 7oQWM98bSuAN1Qtvlrx9uZ8EY4GqqscaErQO9vrAhwgkcedWB jn2lLNjl+G8olJA4uB+Cv5XamrUvziY2pcbCKjFjNt5EQ97Nf2 sBzvlanfrENhV9uOLRpw9DibrzKLh0R1fOrp5xySAe7Ery69 eynt4ItaVWCcpt+CYHFbpHpW/C7INWHeNcaNktr0DBmHh6EWl; '
Supported HTTP versions
The z/OSMF REST interface services support requests in either of the following protocols: HTTP/1.0 or HTTP/1.1
Usage considerations for the z/OSMF REST services
- As with any z/OSMF task or function, the REST services compete for z/OSMF resources with users of the z/OSMF web browser interface. Thus, concurrent high usage of the REST services can affect response time for users of the z/OSMF web browser interface.
- During periods of concurrent high usage of the REST services, an application can experience connection failures, such as connection refused, connection timed out, or connection reset. In these cases, the application should try the request again. The number of retry attempts needed will depend on how much work is being requested of the server. It might be necessary for your installation to modify the workload and reduce the arrival rate of requests.
- Some browsing environments do not support all of the HTTP methods, such as HTML 4 or XHTML 1, or
might block applications from accessing response content having non-successful HTTP response status
codes (4nn and 5nn). As a workaround, your application can use the following custom
HTTP request headers:
- X-IBM-Requested-Method:
- GET, PUT, and DELETE requests can be "tunneled" through a POST method using this custom HTTP header.
- X-IBM-Bypass-Status:
- If set to true, all response status codes are set to 200, and the custom HTTP response header X-IBM-Actual-Status is included in the returned data. To determine the original status code, your application must check the X-IBM-Actual-Status header.
A note on the timestamp data type
The timestamp data type is used in the definition of some data models and notification message formats in the z/OSMF REST services APIs. Where it appears in this document, the timestamp data type is used to mean a non-negative Long integer quantity where the value represents a date and time expressed as the number of milliseconds since midnight on January 1, 1970 UTC.
Allowing cross-site access to REST services
The z/OSMF REST services can be accessed by an HTTP client application, or by a web application running on the host system. By default, z/OSMF blocks access attempts from web applications on remote systems. In such cases, the request is failed with an error message indicating that a cross-site request forgery (CSRF) was attempted.
Your installation can choose to allow cross-site access to REST services on the host system. When you have identified which sites are to be allowed, and which REST interfaces are to be made available for cross-site access, work with your security administrator to create the appropriate authorizations in your z/OS security product. This work involves defining generic or discrete profiles for the remote sites in the ZMFAPLA class, and permitting the profiles to the z/OSMF REST interfaces.
<SAF_PREFIX>.REST.<identifier>.<reversed-hostname>- <SAF_PREFIX> is the SAF prefix for your z/OSMF configuration. By default, this is IZUDFLT.
- REST.<identifier> identifies the REST interface that is to be allowed for
use by the remote site. Table 1
shows the identifiers for each of the z/OSMF
interfaces. To indicate all REST interfaces, specify an asterisk (*) as the identifier.
Table 1. SAF identifiers for the z/OSMF REST interfaces REST interface Identifier Application Linking Manager interface APPLINK Application server routing services GATEWAY 
Cloud provisioning services
PROVISIONING Data persistence services PERSIST Multisystem routing services GATEWAY Software management services SWMGMT Topology services SYSTEM TSO/E address space services TSO z/OS data set and file REST interface FILES z/OS jobs REST interface JOBS z/OSMF workflow services WORKFLOW - <reversed-hostname> is the site’s fully qualified domain name in
reverse, for example, the domain WWW.IBM.COM would be specified as
COM.IBM.WWW. Use uppercase letters for any alphabetic characters in the profile.
Specify a domain name only; not the full URL. Omit the protocol (HTTP:// or
HTTPS://).
If the site is known by an IP address, specify the IP address in reverse. For any IP addresses that you define, it is recommended that you create a discrete profile (without wildcards) for each address. Use a valid "dotted decimal" Internet Protocol version 4 (IPv4) address. IPv6 addresses and internationalized domain name (IDN) addresses are not supported.
Though not recommended, you can use generic profiles with wildcard characters to allow access from multiple domains or sub-domains. You might do so temporarily to allow for internal testing of the REST interfaces across multiple sandbox systems.
- Create a profile for the "lab2.ibm.com" site in the ZMFAPLA class. In the profile, include the
identifier to represent the resource (the REST interface), for example, JOBS to
indicate the z/OS jobs REST interface. In RACF, enter the
RDEFINE command, as
follows:
RDEFINE ZMFAPLA IZUDFLT.REST.JOBS.COM.IBM.LAB2 UACC(NONE)To allow this cross-site access for all of the REST interfaces, specify a wildcard (*) in place of a specific resource identifier. For example:RDEFINE ZMFAPLA IZUDFLT.REST.*.COM.IBM.LAB2 UACC(NONE) - Ensure that the z/OSMF server user ID (by
default, IZUSVR) has READ access to the profile. In RACF, enter the PERMIT
command, as follows:
PERMIT IZUDFLT.REST.JOBS.COM.IBM.LAB2 CLASS(ZMFAPLA) ID(IZUSVR) ACCESS(READ) - Refresh the ZMFAPLA class. In RACF, enter the SETROPTS command, as follows:
SETROPTS RACLIST(ZMFAPLA) REFRESH
Where the z/OSMF REST services are described
- Application Linking Manager interface services
- Application server routing services
- Data persistence services
- Multisystem routing services
- Software management services
- Topology services
- TSO/E address space services
- z/OS data set and file REST interface
- z/OS jobs REST interface
- z/OSMF information retrieval service
- z/OSMF workflow services.
- Application Linking Manager interface services
To perform traditional system management tasks in z/OS, you might interact with several different interfaces, such as the TSO command line, graphical user interfaces, and web-style interfaces. With the z/OSMF Application Linking Manager, it is possible to link or connect some of these tasks and external applications together for a smoother user experience. - Application server routing services
The application server routing services are an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. Use these services to route requests and responses between the client-side and server-side code for any z/OSMF plug-ins you created where the server-side code is hosted on an application server other than the z/OSMF server. - Cloud provisioning services
The cloud provisioning services are a set of application programming interfaces (APIs), which are implemented through industry standard Representational State Transfer (REST) services. These services allow the caller to perform software provisioning for IBM Cloud Provisioning and Management for z/OS. This includes creating instances of IBM® middleware, such as IBM Customer Information Control System (CICS®), IBM DB2®, IBM Information Management System (IMS™), IBM MQ, and IBM WebSphere Application Server (WAS), and creating middleware resources, such as MQ queues, CICS regions, and DB2 databases.. - Data persistence services
The data persistence services 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 user-specific data and global application data, as described in this topic. - Multisystem routing services
To communicate with and transfer data between systems within your enterprise, z/OSMF uses z/OSMF-to-z/OSMF communication. That is, a z/OSMF instance communicates with other z/OSMF instances to collect information from or about the systems in your enterprise. To enable this capability, each system in your enterprise must be accessible by a z/OSMF instance. Typically, this requires deploying one z/OSMF instance in each monoplex or sysplex in your enterprise. - Notification services
The Notification services are provided for both a z/OSMF task and vendor application. These services are used to send a notification in the form of a notification record or email, to a single or multiple recipients. On a successful request, all of the recipients will get the notification in their z/OSMF Notification task as the default destination. A notification can also be sent to the inbox of the user's email account and their mobile application based on preferences. - Software management services
The software management REST interface is an application programming interface (API) implemented through industry standard Representational State Transfer (REST) services. This interface allows a client application to interact with the z/OSMF Software Management task. - Topology services
The topology services 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 the groups, sysplexes, central processor complexes (CPCs), and systems that are defined to z/OSMF, as described in this topic. - TSO/E address space services
The TSO/E address space services 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 TSO/E address spaces on a z/OS system, as described in this topic. - WLM resource pooling services
The WLM resource pooling services are an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. The WLM resource pooling services provide a programming interface for WLM policy elements. You can work with WLM policy elements in the context of IBM Cloud Provisioning and Management for z/OS. - z/OS console services
The z/OS console services are an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. The z/OS console services provide a programming interface for performing z/OS console operations. - 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. - 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. - z/OSMF information retrieval service
The z/OSMF information retrieval service is an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. This service allows the caller to query the version and other details about the instance of z/OSMF running on a particular system. - z/OSMF system variable services
The z/OSMF system variable services are an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. These services allow the caller to create and manage z/OSMF system variables. - z/OSMF workflow services
The z/OSMF workflow services are an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. These services allow the caller to create and manage z/OSMF workflows on a z/OS system.