Intercepting API requester calls

Create an interceptor for monitoring, recording, or validation of API requests sent from a z/OS® application to a REST endpoint, by implementing the InterceptorRequester interface.

The InterceptorRequester interface extends the Interceptor interface and is applicable only to API requester. API requester administrator requests are handled by the Interceptor interface, see Intercepting API provider calls.

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

The preInvokeRequester and postInvokeRequester methods are called for each request, and receive information about the request. An interceptor cannot alter a request in any way. If an interceptor's preInvokeRequester method is called, its postInvokeRequester method is always called. The points at which these methods are called is illustrated in Figure 1.

Figure 1. InterceptorRequester calls
When the request is received from the z/OS application, the preInvokeRequester method is called. The postInvokeRequester method is called just before the response is returned to the client.
one preInvokeRequester
Required interface: InterceptorRequester
The preInvokeRequester method is called when a request is received from the z/OS application 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 preInvokeRequester 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.
four postInvokeRequester
Required interface: InterceptorRequester
The postInvokeRequester method is called just before a response is returned to the z/OS application.
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: 
<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.