Intercepting API provider calls

Create interceptors for monitoring with zosConnect-2.0 and zosConnect-3.0 API requests that are sent from a z/OS application to a REST endpoint by implementing the InterceptorRequester interface. The recording or validation of API requests that are sent from a z/OS application to a REST endpoint is also supported by zosConnect-2.0 by implementing the InterceptorRequester interface.

The Interceptor interface declares four methods: getName, getSequence, preInvoke, and postInvoke. For more information, see com.ibm.zosconnect.spi.Interceptor. The Java™ API documentation for the z/OS Connect SPI is also available as a separate file at <installation_path>/doc/javadoc.zip.

The getName method enables an interceptor to supply the name by which it is referenced in messages. The getSequence method enables an interceptor to return a configured sequence number that is used to specify when this interceptor is run relative to other configured interceptors. For more information, see Configuring monitoring interceptors.

The preInvoke and postInvoke methods are called for all API provider requests unless they have failed authentication or have a malformed URL. They receive a copy of the request and information about the request. The type of request can be determined by calling the Data.getRequestType() method. An interceptor cannot alter a request in any way. If an interceptor's preInvoke method is called, its postInvoke method is always called. The points at which these methods are called is illustrated in Interceptor calls for zosConnect-3.0. The following diagram is an illustration for zosConnect-3.0 with the use of z/OS Assets. The only difference between the zosConnect-2.0 and zosConnect-3.0 implementations is that instead of a z/OS Asset, the zosConnect-2.0 implementation uses service and a service provider instead.

When the request is received from the REST client, the preInvoke method is called. The postInvoke method is called just before the response is returned to the REST client. — Figure 1. Monitoring interceptor calls for z/OS Connect zosConnect-3.0

preInvoke: Required interface: Interceptor; The preInvoke method is called when a request is received from the REST client and initial validation of the request is complete.; zosConnect-2.0 With the zosConnect-2.0 feature, this method can throw an interceptor exception to reject the request. If a request fails initial validation, with z/OS Connect zosConnect-2.0, the request is rejected before the preInvoke method is called.; zosConnect-3.0 With zosConnect-3.0 feature, the exception does not cause the request to be rejected. A request is considered invalid if, for example, it contains an invalid URL or fails user authentication. To capture these failing requests, see Monitoring interceptor interfaces.; zosConnect-3.0 will only write a debug trace for an InterceptorException that is thrown by an interceptor. It will not fail the request.

postInvoke: Required interface: Interceptor; The postInvoke method is called just before a response is returned to the REST client.

The OSGI service metatype definition for the interceptor must set the object class definition (OCD) element attribute ibm:objectClass to com.ibm.zosconnect.interceptorType to indicate the object is an Interceptor. For example: definition:

<OCD id="user.interceptor.ID" ibm:alias="userInterceptorAlias" name="userInterceptorName" 
description="zOSConnect User Interceptor" ibm:objectClass="com.ibm.zosconnect.interceptorType">

For an example of building and deploying an interceptor, see the readme.md file in the A launch icon to indicate a link opens a new tab or window. zosconnect-sample-interceptor repository of the GitHub project zosconnect.

For information about interfaces that provide additional interceptor points, see Monitoring interceptor interfaces.