Clarify API Product Behaviour When Native API Resources Are Updated

Description

There is a documentation gap regarding how API Products behave when an update is made to a native API resource (e.g., addition or removal of a mediation policy, custom sequence, or other resource-level configuration).

Currently, the documentation does not clearly explain that API Products do not automatically reflect changes made to underlying API resources upon redeployment of the API Product.

Observed Behaviour

When a resource-level update is applied to a native API and the API is redeployed:

• The native API correctly reflects the new policy or mediation logic.
• However, any API Product that includes that resource will continue using the older resource configuration, even if the API Product is redeployed via a new revision.

The updated behaviour is only picked up when the user manually selects Save or Save and Deploy in the Manage Resources view of the API Product in the Publisher Portal. This action triggers the required API Product update flow.

Expected Behaviour (Current Product Design)

This is the intended behaviour according to the product design:

• API Products do not automatically re-sync resource-level policies from native APIs on product redeployment alone.
• A user must explicitly perform Save or Save and Deploy in the API Product's Manage Resources section.
• This action triggers the internal updateAPIProduct[1] call, ensuring the updated resource configuration is reflected inside any API Product that uses it.

Missing Documentation

Current documentation does not clearly state:

1. That resource updates in a native API are not automatically propagated to API Products.
2. That the correct workflow is to use Save / Save and Deploy in Manage Resources.
3. Why this behaviour occurs and what underlying API Product update call is triggered.
4. The relation between resource-level updates and product-level swagger regeneration.

Suggested Improvement

• A clear explanation of how API Products consume resource definitions from native APIs.
• A description of the required Manage Resources → Save / Save and Deploy action for reflecting updates.
• A note that redeploying an API Product without performing the above will not refresh inherited policies.

Version(s)

4.4.0 and Others

Start by reviewing the existing API Product and native API documentation for version 4.4.0, focusing on the Manage Resources view and product redeployment workflow. Document that native API resource changes are not propagated by product redeployment alone, and explain when Save or Save and Deploy is required. Done means the workflow, updateAPIProduct call, and relationship to product-level swagger regeneration are clear.