Written by Jack Dunning
In this blog we will explore the use of API specific policies and provide a complete example of the end to end process. This example will show many of the capabilities that are available in policy.
A policy is a set of rules that allow you to override previously defined properties, based on the header values in API requests. Policy support provides the following functionality:
- Support for overriding IMS connection reference, interaction references, and transaction code.
- Support for overriding CICS connection references, CCSID values (code pages), and transaction IDs.
- Support for using variable substitution in rules.
- Support for multiple headers in rule conditions.
- Granular control of policies by allowing a policy to be set on individual APIs.
For a review on some of the problems solved by z/OS Connect EE policies, see our earlier blog Using policy-based API processing in z/OS Connect EE.
Why apply a specific policy to an API?
An example use case
A company has the majority of their development teams in the US, but has recently formed new development teams in France and Sweden.
The company manages the routing to production or development systems in the US by creating multiple versions of their services and then mapping these services to different resource paths within their APIs.
The existing solution for the US team requires a service to be duplicated to change the connection reference used during an API call to be one of two options configured in server.xml for production or development.
<zosconnect_cicsIpicConnection id="Production" host="us.example.com" port="1001" />
<zosconnect_cicsIpicConnection id="Development" host="us.example.com" port="1002" />
To call a specific subsystem, the developers had to use a different resource path in their API.
curl GET https://example.com/api/production/item/1234
curl GET https://example.com/api/development/item/1234
Using the current format of the API, the company would need to add in another layer to allow for the country to be specified, meaning that six different resource paths are required for a single operation.
curl GET https://example.com/api/development/us/item/1234
This makes even minor changes on these services a large development effort, as each version must be updated and kept in sync. This workaround is not sustainable, especially with the added complexity from the new development teams.
To avoid these issues the following requirements need to be satisfied:
- Each location has a production and development CICS region which can be used.
- The teams in France and Sweden need to handle data differently for a specific API, called customer, so that it can call the local CICS regions for each country.
- A different code page must be used for the CICS regions in France and Sweden when the customer API is called.
After searching, the development team discover they can apply a global policy to select either the production or development subsystem. A specific policy can also be set for the customer API to allow the additional attributes to be overridden by the French and Swedish developers.
How to call a specific endpoint using a z/OS Connect EE policy
Instead of requiring different resource paths in every API, a policy can be created to handle the affinity. First a policy is defined in server.xml, which points to a rule set file.
<zosconnect_policy id="genericPolicy" location="/var/zosconnect/rules">
<ruleset file="genericRules.xml"/>
</zosconnect_policy>
Then a reference is made to the policy in the zosconnect_zosConnectAPIs element to apply the policy to all API requests. The policy referenced by the zosconnect_zosConnectAPIs element is called the global policy.
<zosconnect_zosConnectAPIs policyRef="genericPolicy" />
The rule set file genericRules.xml contains one rule:
<ruleset name="generic rules">
<rule name="system-rule">
<conditions>
<header name="system" value="Production,Development"/>
</conditions>
<actions>
<set property="cicsConnectionRef" value="${system}"/>
</actions>
</rule>
</ruleset>
The developers enhance their APIs to include the header system on a request (see step 4 in our previous blog), so that the header is exposed in the Swagger document to be consumed. The rule exploits the variable substitution features to allow HTTP header values in the rule to modify the action.
Update the server configuration and look for message BAQR7056I.
BAQR7056I: z/OS Connect EE policy genericPolicy is active.
The developers can then call either the production or development CICS region by including the system header on their API requests with the desired value, thus removing the need for custom resource paths and changes to the CICS services.
Note: If the policy rules are not matched, the connection reference defined by the service will be used (in this example this connection does not exist and so the request will fail).
curl --header "system:Development" GET https://example.com/api/item/1234
How to apply a policy to a specific API
The next step is to support the specific requirements of the new development teams, who need to be able to manage the customer API so that it can target their local CICS regions (including changing the code page used), rather than the US CICS region.
To allow the customer API to satisfy these requirements, a policy with rules specific to the API can be configured. The desired topology is as follows:
Four new IPIC connections have been configured in server.xml, which are later referenced by the policy rules.
<zosconnect_cicsIpicConnection id="FRA-Production" host="france.example.com" port="1001" />
<zosconnect_cicsIpicConnection id="FRA-Development" host="france.example.com" port="1002" />
<zosconnect_cicsIpicConnection id="SWE-Production" host="sweden.example.com" port="1001" />
<zosconnect_cicsIpicConnection id="SWE-Development" host="sweden.example.com" port="1002" />
Again, the system programmer begins by defining the policy in server.xml.
<zosconnect_policy id="customerPolicy" location="/var/zosconnect/rules">
<ruleset file="customerRules.xml"/>
</zosconnect_policy>
Like the previous policy, this one needs to be referenced to be activated, but this time at a more granular level – by the API configuration.
Note: Policies named on an API replace those that are defined globally on the zosconnect_zosConnectAPIs element.
<zosconnect_zosConnectAPIs policyRef="genericPolicy">
<zosConnectAPI name="customer" policyRef="customerPolicy" />
</zosconnect_zosConnectAPIs>
The rules within the customerRules.xml file are as follows.
<ruleset name="customer rules">
<rule name="french-rule">
<conditions>
<header name="country" value="FRA"/>
<header name="system" value="Production,Development"/>
</conditions>
<actions>
<set property="cicsCcsid" value="297"/>
<set property="cicsConnectionRef" value="FRA-${system}" />
</actions>
</rule>
<rule name="swedish-rule">
<conditions>
<header name="country" value="SWE"/>
<header name="system" value="Production,Development"/>
</conditions>
<actions>
<set property="cicsCcsid" value="278" />
<set property="cicsConnectionRef" value="SWE-${system}" />
</actions>
</rule>
<rule name="system-rule">
<conditions>
<header name="system" value="Production,Development"/>
</conditions>
<actions>
<set property="cicsConnectionRef" value="${system}"/>
</actions>
</rule>
</ruleset>
As the teams not in France or Sweden still need to be able to call the customer API, the previously created rule named system-rule has been included.
Note: As system-rule is using the same header, but is less specific than both french-rule and swedish-rule (as it matches against only one header compared to two headers), it will only be applied if neither french-rule or swedish-rule are applied.
A rule has then been added for both France and Sweden to allow for both the connection to be selected and the correct code page to be specified (via CCSID).
Update the server configuration and look for message BAQR7082I.
BAQR7082I: z/OS Connect EE policy customerPolicy is active for API customer.
The developers in France and Sweden can now call the APIs in the following way (choosing country and system headers value as required):
curl --header "system:Production" --header "country:FRA" GET https://example.com/api/item/1234
Success! API specific affinities are now managed using policies
z/OS Connect EE policies have allowed us to greatly simplify the usage and management of APIs by moving the application affinities out of the API itself and into the simple rules files used by policies.
For more information on z/OS Connect EE policies – see the IBM Knowledge Center.