What problem does policy-based processing solve?

When making an API available, whether in a production or test environment, you can easily find yourself needing to send identical requests to different instances of the same z/OS subsystem:

This might be driven by a business need, such as a requirement to route API calls based on where a request comes from. Or you might have a technical need, such as routing certain API calls to a different version of an application, available on a specific instance of a subsystem.

Whatever the reason, you need a smart way to manage the affinity between the API call and the backend subsystem.

One way to do this is to create duplicate service definitions with almost identical configurations, and multiple resource paths in your APIs. But, this leads to unnecessary maintenance for your administrators, and unwanted complexity for your API consumers.

Fortunately, you can accomplish the same thing without the administrative headache, by using a policy.

In z/OS Connect EE V3.0.3, our first policy-based release, we added policy-based API processing for APIs that target IMS applications.

An example use case

Call a beta version of an application, with only a header change to the API call

Anne and Chris each run a development team. Anne’s team need to call a stable version of an application, whereas Chris’ team need to call a beta version. They want to ensure that each of their team members can call different versions of the application, without editing the API path or creating more churn for their z/OS administrator.

They can achieve this by using policy-based API processing.

Using Anne and Chris’s use case, this article demonstrates how you might configure policy-based API processing for an API that calls an IMS service, which routes to one of two IMS Connect regions depending on the value of the HTTP header in the API request.

Setting up policy-based API processing

Prerequisites

These steps assume:

• a deployed service and API exist in z/OS Connect EE that calls an IMS application.
• there are additional instances of the same IMS application already running in parallel IMS regions, which sit behind their own IMS Connect region.

1. Define/edit the IMS connections

For this scenario, we define two connections to IMS Connect regions in the IMS mobile service registry:

<imsmobile_imsConnection comment="IMS Connect for Anne's team" 
                            connectionFactoryRef="oneCF" 
                            connectionTimeout="-1" 
                            connectionType="IMSCONNECT" 
                            id="connectionStable" />

   <connectionFactory id="oneCF">
      <properties.gmoa hostName="example.com" 
                       portNumber="10801" />
   </connectionFactory>


   <imsmobile_imsConnection comment="IMS Connect for Chris's team" 
                            connectionFactoryRef="twoCF" 
                            connectionTimeout="-1" 
                            connectionType="IMSCONNECT" 
                            id="connectionBeta" />

   <connectionFactory id="twoCF">
      <properties.gmoa hostName="example.com" 
                       portNumber="10802" />
   </connectionFactory>

The service is configured in the server.xml:

<zosconnect_services updateTrigger="polled" 
                     pollingRate="5s"/>
   <service name="ImsApplication" 
            imsInteractionRef="interactionStable"
            imsConnectionRef=""/>
   </service/>
</zosconnect_services/>

Note: Incoming requests that do not match a rule in the policy will use the value that is configured in the service. In this example, the we have left the imsConnectionRef element blank, which means that a request that doesn’t match a rule will fail, but you could specify a value here instead.

2. Create your rule set file

A policy is described in a rule set file that describes which HTTP header should be matched and the values that should be dynamically applied to certain properties at runtime.

For this scenario, we have two rules, one for each development team:

<ruleset name="teamRouting">
   <rule name="teamOne">
      <conditions>
         <header name="team" value="Anne,Boris" />
      </conditions>
      <actions>
         <set property="imsConnectionRef" value="connectionStable" />
      </actions>
   </rule>

   <rule name="teamTwo">
      <conditions>
         <header name="team" value="Chris,Denise,Eric" />
      </conditions>
      <actions>
         <set property="imsConnectionRef" value="connectionBeta" />
      </actions>
   </rule>
</ruleset>

These rules match on an HTTP header with the name team, where values of Anne or Boris will set imsConnectionRef=connectionStable and values of Chris, Denise, or Eric will set imsConnectionRef=connectionBeta.

Anything other than those cases will cause the request to fail.

In order to use the ruleset, it needs to be stored in the resources/zosconnect/rules directory in the server directory.

3. Define and enable the policy

Define the policy in server.xml:

<zosconnect_policy id="teamRouting" >
   <ruleset file="teamRouting.xml" />
</zosconnect_policy>

Finally, add a link to the policy definition in the zosconnect_zosConnectApis element:

<zosconnect_zosConnectApis policyRef="teamRouting" />

Note: Policies are not currently supported on individual zosConnectAPI elements.

4. Add the header to your API definition

API consumers need to know that the header is now a required element on their API call.

You can add the header to the API definition in the API toolkit, as part of the request mapping for the API operation. This will then appear in the Swagger documentation for the API.

1. In the API toolkit, open the request mapping for the operation.
2. Right click on the Headers section, and select Add HTTP Header.
3. Change the name to team, check Required, and click OK.
4. Save your changes, and re-deploy your API.
   

5. Start the server

Once the server starts, a message is written to the log that indicates your policy is active:

BAQR7056I: z/OS Connect EE policy teamRouting is active.

6. What the API call looks like

Now, if Anne or one of her teammates make a call to the API, they will use their name in the header, and invoke the stable version of the application. So, a cURL would look something like this:

curl --header "team:Anne" GET https://example.com/api/item/1042

Chris’ team can use one of their names, and will invoke the beta version of the application:

curl --header "team:Chris" GET https://example.com/api/item/1042