Intercepting API provider calls

Create an interceptor for monitoring, recording, or validation of API requests sent to a System of Record (SoR) and IBM® z/OS® Connect administration requests, by implementing the Interceptor 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 interceptors.

The preInvoke and postInvoke methods are called for API, direct service, and all administration requests. 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 Figure 1.

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. Interceptor calls

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. This method can throw an interceptor exception to reject the request. If a request fails initial validation, the request is rejected before the preInvoke method is called. A request is considered invalid if, for example, it contains an invalid URL or fails user authentication. To capture these failing requests, see Creating a monitoring interceptor.
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 zosconnect-sample-interceptor repository of the GitHub project zosconnect.

For information about interfaces that provide additional interceptor points, see Creating a monitoring interceptor.