Handling API and Common Policies with Identical Names and Versions in WSO2 API Manager 4.2.0

Note: This feature was introduced as a patch to WSO2 API Manager 4.2.0, so ensure you’re updated to version 4.2.0.117 or later to access it.

WSO2 API Manager 4.2.0 introduces the capability to have both an API policy and a Common policy with the same name and version, from the above mentioned update level onwards. This enhancement directly impacts the API import/export flow, alongside UI modifications. This article explains the reasoning behind these visible changes to the users.

API Export

Previously, when an API was exported, the unzipped API directory contained a folder storing policies attached to that API, structured as follows:

Directory structure for an exported API before update level 4.2.0.117

In the previous implementation, WSO2 API Manager would search for files named in the format <policy-name>_<policy-version> and discards any entries with duplicate policy file names without adding to the policy directory. Since this behaviour conflicted with the newly addressed feature, the API export flow has been adjusted. Now, policy files are stored in a format that accommodates both API and Common policies with the same name and version.

Directory structure for an exported API from update level 4.2.0.117

This enhancement allows both types of policies with identical names and versions to be attached to a single API without conflict.

API Import

In the existing setup, the import process reviews the API definition file (of JSON or YAML format) to identify policies attached to each operation. It iterates through these operations and checks for the corresponding policy file named <policy-name>_<policy-version>. With the new update, the policy type is also included, and the file naming format has changed to <policy-name>_<policy-version>_<policy-type>.

Consider a simplified scenario where you have a single resource and attach an API policy named ‘policy1’ with version ‘v1’ to the /GET path and a Common policy named 'policy1' with version 'v1' to the /PUT path. The api.yaml file would only indicate that both /GET and /PUT paths have a policy named 'policy1' with version 'v1', making it difficult to match the policy specified in each path to the appropriate policy file in the export directory.

To resolve this, the API definition file (api.json or api.yaml) now includes a new field called policyType under operationPolicies. Technically, this change adds a policyType attribute in the operationPolicyDTO, with that modifying the ApiDTO structure.

Note: APIs exported in previous update levels can still be imported in this updated level, even if they use the previous policy file naming format.

Impact on API Products

When exporting an API Product, the associated APIs are exported within subdirectories, with policy files adhering to the new naming convention.

Additionally, during API Product resource updates, such as when resources with some policies are removed or new resources with some new policies are added, the correct policy attachment is expected to occur by factoring in the policy type.

We encourage you to upgrade to the latest update level to take full advantage of these new features and enjoy a smoother API management experience in WSO2 API Manager!