Setting up the z/OS Connect REST client service

The z/OS Connect REST Client support enables z/OS Connect users to route requests to remote REST applications through z/OS Connect; therefore, taking advantage of the existing interceptor infrastructure.

About this task

This function is available when you configure the zosConnect-1.2 feature. The z/OS Connect REST Client service is a z/OS Connect service SPI implementation. Requests that invoke this service are made in two ways:

  • Use the ?action=invoke query parameter mechanism as follows: https://hostName:port/zosConnect/services/serviceY?action=invoke where serviceY is the service name that is associated with the configured zosConnectServiceRestClient element.
  • Use the zosConnectService attribute definition that is called invokeURI. You can use this attribute to define a custom URI that is associated with a service name and any of the following HTTP verbs: GET, POST, PUT, DELETE; for example:
    <zosConnectService serviceName="serviceY" serviceRef="restClientServiceY" invokeURI="/my/custom/uri" />

An example of a service invocation for the defined service is: https://host:port/my/custom/uri (HTTP verb: GET/POST/PUT/DELETE). z/OS Connect understands the association between the invokeURI attribute and the serviceName attribute defined in the example. z/OS Connect calls the invoke method on the implementation of the z/OS Connect associated service (restClientServiceY).

For more information on the capability and flexibility that the invokeURI attribute offers, see the documentation for z/OS Connect 1.2.

Stabilized features: The zosConnect-1.0 and zosConnect-1.2 features are stabilized. You can continue to use the features. However, consider using the IBM z/OS Connect Enterprise Edition product.

Procedure

  1. Configure the zosConnectServiceRestClient element and associate it with a zosConnectService element. 
    <featureManager>
	 <feature>zosConnect-1.2</feature>
</featureManager>

<!-- Global interceptor definition to run for all service requests -->
<zosConnectInterceptors interceptorRef="auth,audit,fileSystemLogger" id="globalInterceptorList1"/>
<fileSystemloggerInterceptor id="fileSystemLogger" logName="service1Log_%SERVERNAME%"sequence="1"/>
<authorizationInterceptor id="auth" sequence="2"/>
<auditInterceptor id="audit" sequence="3"/>
    
<!-- ZosConnectManager definition -->
<zosConnectManager globalAdminGroup="ADMIN" 
                   globalOperationsGroup="OPS" 
                   globalInvokeGroup="INVOKE"
                   globalInterceptorsRef="globalInterceptorList1"/>

<zosConnectServiceRestClient id="restClientServiceY" 
                             host="remoteHostName" 
                             port="8800" 
                             uri="/remote/endpoint" 
                             httpMethod="DELETE"/>
<zosConnectService serviceName="serviceY" serviceRef="restClientServiceY"invokeURI="/my/custom/uri" />

    In the example, requests that target the serviceY service are routed to the remote host and port that is configured under the associated restClientServiceY service and that uses the configured URI and DELETE HTTP method. The JSON payload is automatically sent with the remote request. When you configure the zosConnectServiceRestClient element, specify the host name and port number attributes. If you do not specify the uri or httpMethod attributes, the values that are used are the ones from the original client request that is targeting the serviceY service. The example also shows that because interceptors are configured to run globally, every request that targets the serviceY service is logged, authorized, and audited before it is routed to the remote endpoint. The interceptors also log and audit the responses on the return from the remote endpoint. Because an invokeURI attribute is configured for the serviceY service, the requester can start the implementation of the serviceY invoke method by using the following URL: https://host:port/my/custom/uri and using either the GET, POST, PUT, or DELETE HTTP method. In this case, because the serviceY service refers to an instance of the z/OS Connect REST client service, the invoke() method on this instance is called. For more information about available configuration attributes and default values see the documentation for z/OS Connect 1.0 and z/OS Connect 1.2.

  2. (Optional) Configure basic authentication. Add the appSecurity-2.0 feature to the server.xml file. 
    <featureManager>
	 <feature>zosConnect-1.2</feature>
	 <feature>appSecurity-2.0</feature>
</featureManager>

<zosConnectServiceRestClientBasicAuth id="fredBasicAuth" userName="Fred" password="{xor}OS06Oy8oOw=="/>

<zosConnectServiceRestClient id="restClientServiceY" 
                             host="remoteHostName" 
                             port="8800" 
                             uri="/remote/endpoint" 
                             httpMethod="POST" 
                             basicAuthRef="bobBasicAuth"/>

<zosConnectService serviceName="serviceY" serviceRef="restClientServiceY" />

    The configuration enables the user name and password that is configured for the zosConnectServiceRestClientBasicAuth element to be propagated when the request to the remote REST application endpoint is made.

  3. (Optional) Configure certificate authentication. Add the appSecurity-2.0 feature to the server.xml file.

    The example shows how to configure the client keystore and client truststore and associate them with the zosConnectServiceRestClient configuration.

    <featureManager>
	 <feature>zosConnect-1.2</feature>
	 <feature>appSecurity-2.0</feature>
</featureManager>

<keyStore id="clientKeyStore" password="zosConnect"
          location="${server.config.dir}/resources/security/clientKey.jks" />

<keyStore id="clientTrustStore" password="zosConnect"
          location="${server.config.dir}/resources/security/clientTrust.jks" />

<ssl id="sslCertificates" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore"/>

<zosConnectServiceRestClient id="restClientServiceY" 
                             host="remoteHostName" 
                             port="8800" 
                             uri="/remote/endpoint"  
                             httpMethod="PUT" 
                             sslCertsRef="sslCertificates"/>

<zosConnectService serviceName="serviceY" serviceRef="restClientServiceY" />