Merge pull request #1575 from wso2/Nashaath-patch-33

Add content on applying advanced settings on mediation policies

en/.spelling

@@ -702,6 +702,8 @@ headerName
 fooValue
 authzHeaderValue
 myResourcePath
+evictable
+defaultable
 WebSocket
 WebSockets
 expose-a-nodejs-websocket-endpoint-via-a-service

en/docs/api-management/api-policies/about-api-policies.md

@@ -0,0 +1,25 @@
+# About API Policies
+
+API policies are units of business logic that you can apply to modify the flow of API invocations. 
+
+You can apply a policy to alter the  `Request`, `Response`, or `Error` flow of an API invocation before it reaches the backend or the client. For example, you can add a policy to the response flow to transform the payload from JSON to XML and add a header to the response. 
+
+## Inbuilt mediation policies
+
+Choreo supports a set of inbuilt mediation policies that can handle common API transformation and mediation tasks. These policies run within a single mediation service, making it straightforward to implement and manage complex mediation logic. The following inbuilt policies are available in Choreo:
+
+- **JSON to XML**: Transforms a JSON payload in a request or response into XML format. This policy is applicable only to JSON payloads in mediation flows. Applying it to a non-JSON payload terminates the flow. This policy cannot be used more than once on the same resource because the payload will already be converted to XML.
+- **XML to JSON**: Converts an XML payload in a request or response into JSON format. This policy is applicable only to XML payloads in mediation flows. Applying it to a non-XML payload terminates the flow. This policy cannot be used more than once on the same resource because the payload will already be converted to JSON.
+- **Remove Query Parameter**: Removes specified query parameters from a request. You can use this policy multiple times to remove different parameters. Attempting to remove a non-existent parameter has no effect. If the parameter exists, it will be removed; otherwise, the request proceeds as usual.
+- **Remove Header**: Removes specified headers from a request or response. You can attach this policy multiple times to remove multiple headers. The header name must be static, but you can use placeholders to configure different values for different environments. For example, `${headerName}`.
+- **Add Query Parameter**: Adds query parameters to a request. You can attach this policy multiple times to add various parameters. Adding the same parameter multiple times creates an array of values. The parameter name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${fooValue}`.
+- **Add Header**: Adds headers to a request or response. If the same header is added multiple times, values are appended rather than overwritten. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${authzHeaderValue}`.
+- **Set Header**: Sets headers in a request or response, overwriting any existing values. You can attach this policy multiple times to set multiple headers. Each time the same header is set, it replaces the previous value. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${authzHeaderValue}`. 
+- **Rewrite Resource Path**: Modifies the resource path of an HTTP request by replacing the original path with a new relative path. You can apply this policy multiple times, but only the last instance will take effect. The new path must be static, but you can use placeholders to configure different values for different environments. For example, `${myResourcePath}`.
+- **Log Message**: Logs the payload and headers of a request or response. Attaching this policy multiple times results in duplicate log entries. By default, headers and payloads are not logged. To log them, you can enable `Log Headers` and `Log Payload` parameters. To exclude specific headers when logging, you can use the `Excluded Headers` parameter, which takes a comma-separated list of header names. An error will occur if payload logging is enabled but the payload cannot be read.
+
+These inbuilt mediation policies provide flexibility to manage API requests and responses, allowing for custom transformations and logic without requiring custom code.
+
+For details on attaching and managing one or more policies to an API proxy component implementation via the Choreo Console, see [Attach and Manage Policies](../api-policies/attach-and-manage-policies.md).
+
+For details on applying advanced settings on mediation policies, see [Apply Advanced Settings on Mediation Policies](../api-policies/apply-advanced-settings-on-mediation-policies.md).

en/docs/api-management/api-policies/apply-advanced-settings-on-mediation-policies.md

@@ -0,0 +1,28 @@
+# Apply Advanced Settings on Mediation Policies
+
+Advanced settings for mediation policies are available for proxy components with an attached mediation policy. For details on attaching a mediation policy to a proxy component, see [Attach and Manage Policies](../api-policies/attach-and-manage-policies.md).
+
+The approach to applying advanced settings depends on whether the proxy component is deployed or not.
+
+## Mediation policy advanced settings
+
+| **Setting**                     | **Purpose**    | **How to apply**  | **Impact**   |
+|---------------------------------|----------------|-------------------|--------------|
+| **HTTP version**                | By default, Choreo supports HTTP 1.1. If necessary, you can change to HTTP 1.0 or HTTP 2.0. | Specify the required HTTP version in the **Advanced Settings** field. <br> ![HTTP version setting](../../assets/img/api-management/api-policies/advanced-settings/http-version-setting.png) | The mediation application will use the specified HTTP version when interacting with backend services.  |
+| **Hostname verification**       | Choreo enables hostname verification by default when using mTLS. You can disable it if necessary. | Set the `verifyHostname` parameter to `false` in the **Advanced Settings** field. <br> ![Hostname verification setting](../../assets/img/api-management/api-policies/advanced-settings/hostname-verification-setting.png)   | Hostname verification will be skipped during mTLS interactions.                              |
+| **Minimum evictable idle time** | Determines how long (in seconds) an outgoing connection remains idle before eviction. The default is 300 seconds. | Set the required idle time in the **Advanced Settings** field. <br> ![Minimum evictable idle time setting](../../assets/img/api-management/api-policies/advanced-settings/minimum-evictable-idle-time-setting.png)          | Idle connections will be closed and evicted after the defined period.                    |
+| **Detailed access log**         | By default, logs related to the mediation application are generated and can be viewed as [runtime logs](../../monitoring-and-insights/view-logs.md#runtime-logs). You can disable these logs if necessary.      | Set the `detailedAccessLog` parameter in the **Advanced Settings** field. <br> ![Detailed access log setting](../../assets/img/api-management/api-policies/advanced-settings/detailed-access-log-setting.png)  | Logs related to the mediation application will not be generated.    |
+
+## Configure advanced settings for a proxy component
+
+To configure advanced settings for a proxy component with an attached mediation policy, follow these steps:
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev).
+2. In the **Component Listing** pane, click on the REST API Proxy component for which you want to configure advanced settings.
+3. In the left navigation menu, click **Deploy**.
+4. Depending on the deployment status of the proxy component, follow one of these steps:
+   - If the proxy component is not deployed, go to the **Set Up** card and click **Configure & Deploy**. 
+   - If the proxy component is already deployed, go to the respective environment card depending on the environment you want to apply advanced settings, and then click the **Environment Variables** icon.
+5. In the **Configurations** pane that opens, expand the **Defaultable Configurables** section. 
+6. In the **Advanced Settings** field, configure the necessary settings as described in the [Mediation policy advanced settings](#mediation-policy-advanced-settings) section.
+7. Click **Save & Deploy**.

en/docs/api-management/api-policies.md → en/docs/api-management/api-policies/attach-and-manage-policies.md

@@ -1,26 +1,4 @@
-# API Policies
-
-API policies are units of business logic that you can apply to modify the flow of API invocations. 
-
-You can apply a policy to alter the  `Request`, `Response`, or `Error` flow of an API invocation before it reaches the backend or the client. For example, you can add a policy to the response flow to transform the payload from JSON to XML and add a header to the response. 
-
-## Inbuilt mediation policies
-
-Choreo supports a set of inbuilt mediation policies that can handle common API transformation and mediation tasks. These policies run within a single mediation service, making it straightforward to implement and manage complex mediation logic. The following inbuilt policies are available in Choreo:
-
-- **JSON to XML**: Transforms a JSON payload in a request or response into XML format. This policy is applicable only to JSON payloads in mediation flows. Applying it to a non-JSON payload terminates the flow. This policy cannot be used more than once on the same resource because the payload will already be converted to XML.
-- **XML to JSON**: Converts an XML payload in a request or response into JSON format. This policy is applicable only to XML payloads in mediation flows. Applying it to a non-XML payload terminates the flow. This policy cannot be used more than once on the same resource because the payload will already be converted to JSON.
-- **Remove Query Parameter**: Removes specified query parameters from a request. You can use this policy multiple times to remove different parameters. Attempting to remove a non-existent parameter has no effect. If the parameter exists, it will be removed; otherwise, the request proceeds as usual.
-- **Remove Header**: Removes specified headers from a request or response. You can attach this policy multiple times to remove multiple headers. The header name must be static, but you can use placeholders to configure different values for different environments. For example, `${headerName}`.
-- **Add Query Parameter**: Adds query parameters to a request. You can attach this policy multiple times to add various parameters. Adding the same parameter multiple times creates an array of values. The parameter name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${fooValue}`.
-- **Add Header**: Adds headers to a request or response. If the same header is added multiple times, values are appended rather than overwritten. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${authzHeaderValue}`.
-- **Set Header**: Sets headers in a request or response, overwriting any existing values. You can attach this policy multiple times to set multiple headers. Each time the same header is set, it replaces the previous value. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${authzHeaderValue}`. 
-- **Rewrite Resource Path**: Modifies the resource path of an HTTP request by replacing the original path with a new relative path. You can apply this policy multiple times, but only the last instance will take effect. The new path must be static, but you can use placeholders to configure different values for different environments. For example, `${myResourcePath}`.
-- **Log Message**: Logs the payload and headers of a request or response. Attaching this policy multiple times results in duplicate log entries. By default, headers and payloads are not logged. To log them, you can enable `Log Headers` and `Log Payload` parameters. To exclude specific headers when logging, you can use the `Excluded Headers` parameter, which takes a comma-separated list of header names. An error will occur if payload logging is enabled but the payload cannot be read.
-
-These inbuilt mediation policies provide flexibility to manage API requests and responses, allowing for custom transformations and logic without requiring custom code.
-
-## Attach and manage mediation policies
+# Attach and Manage Policies
 
 You can easily attach one or more policies to an API proxy component implementation via the Choreo Console. If necessary, you can also rearrange or swap the policies you attach.
 
@@ -36,7 +14,7 @@ In Choreo, when you attach a mediation policy to a proxy, the deployment is a tw
 
 When a mediation policy is attached to a specific flow, the API invocation undergoes the following behavioral modification:
 
- ![Request/Response flow](../assets/img/api-management/api-policies/request-response-flow.png)
+ ![Request/Response flow](../../assets/img/api-management/api-policies/request-response-flow.png)
 
  - In the request path, the requests that pass through the gateway reach the relevant component, and Choreo executes any attached policies to the resource's request path before sending it to the backend. 
 
@@ -56,7 +34,7 @@ To attach a policy to the `Request`, `Response`, or `Error` flow of a REST API p
 6. In the **Policy List** pane that opens, click on a required policy to view its details.
 7. If the attached policy requires parameter configuration, on the policy pane enter the appropriate values and configure the parameters. To make a parameter a configurable variable, input the value in the `${<variableName>}` format. For example, you can use `${name}` as an example.
 
-    ![Configure parameters](../assets/img/api-management/api-policies/configure-parameters.png)
+    ![Configure parameters](../../assets/img/api-management/api-policies/configure-parameters.png)
 
 8. To attach the policy, click **Add**.
 
@@ -67,7 +45,7 @@ To deploy the API follow the steps below:
 
 10. In the **Configure & Deploy** pane, if you have any configurable variables that require values, specify appropriate values for them.
 
-     ![Save and deploy values](../assets/img/api-management/api-policies/save-and-deploy.png){.cInlineImage-full}
+     ![Save and deploy values](../../assets/img/api-management/api-policies/save-and-deploy.png)
 
 11. Click **Save & Deploy**.
 
@@ -86,8 +64,6 @@ If none of the above changes occur during deployment, Choreo skips the code gene
     - If you want to enforce the code generation and build process of the mediation application in instances where the specified changes do not take place, you must turn on the **Refresh Mediation Policies** toggle when you configure and deploy the component. 
     - It is useful to enable **Refresh Mediation Policies** when you want to incorporate the latest Ballerina patches for your generated mediation application. However, this can result in longer deployment times.
 
-
-
 ## Implement an API policy
 
 Choreo allows you to implement an API policy as a Ballerina project and attach it to an API proxy component. 
@@ -129,7 +105,7 @@ To create a Ballerina project for the mediation policy using `mediation.template
 ```
  The Ballerina project that is created should have the following content: 
 
-![Ballerina project](../assets/img/api-management/api-policies/ballerina-project.png){.cInlineImage-xsmall}
+![Ballerina project](../../assets/img/api-management/api-policies/ballerina-project.png)
 
 Depending on your requirement, you can modify the `Ballerina.toml` and the `Package.md` files of the generated project. For example, you can update the org, package, package version, API documentation content, keywords, etc.
 
@@ -273,7 +249,7 @@ To publish the policy, follow the steps given below:
 
 Once you publish the package, it will appear as follows in the policy list:
 
-![Published policy](../assets/img/api-management/api-policies/published-policy.png){.cInlineImage-small}
+![Published policy](../../assets/img/api-management/api-policies/published-policy.png)
 
 ### Write unit tests
 

en/mkdocs.yml

@@ -183,7 +183,10 @@ nav:
       - Lifecycle Management: api-management/lifecycle-management.md
       - Documents: api-management/documents.md
       - API Rate Limiting: api-management/api-rate-limiting.md
-      - API Policies: api-management/api-policies.md
+      - API Policies:
+          - About API Policies: api-management/api-policies/about-api-policies.md
+          - Attach and Manage Policies: api-management/api-policies/attach-and-manage-policies.md
+          - Apply Advanced Settings on Mediation Policies: api-management/api-policies/apply-advanced-settings-on-mediation-policies.md
       - Control API Visibility: api-management/control-api-visibility.md
       - Manage API Traffic:
           - Assign Subscription Plans to APIs: api-management/manage-api-traffic/assign-subscription-plans-to-apis.md
@@ -398,6 +401,7 @@ plugins:
           'manage-databases-and-caches/choreo-managed-redis-datastores.md': 'https://wso2.com/choreo/docs/manage-databases-and-caches/choreo-managed-caches/'
           'monitoring-and-insights/usage-insights.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/insights-overview/'
           'develop-components/configure-mutual-tls-between-components.md': 'https://wso2.com/choreo/docs/authentication-and-authorization/configure-mutual-tls-between-components/'
+          'api-management/api-policies.md': 'https://wso2.com/choreo/docs/api-management/api-policies/about-api-policies/'
 
 extra_css:
   # - assets/lib/highlightjs/default.min.css