Merge pull request #677 from sgayangi/658-1.2.0

[1.2.0] Update API Policy documentation
wso2 · Nov 20, 2024 · 4fa6dec · 4fa6dec
2 parents fc1ab98 + 9210d6e
commit 4fa6dec
Show file tree

Hide file tree

Showing 28 changed files with 219 additions and 67 deletions.
diff --git a/en/docs/assets/img/api-policies/add-header-policy.png b/en/docs/assets/img/api-policies/add-header-policy.png
diff --git a/en/docs/assets/img/api-policies/api-level-policies.png b/en/docs/assets/img/api-policies/api-level-policies.png
diff --git a/en/docs/assets/img/api-policies/attached-add-header.png b/en/docs/assets/img/api-policies/attached-add-header.png
diff --git a/en/docs/assets/img/api-policies/backend-jwt.png b/en/docs/assets/img/api-policies/backend-jwt.png
diff --git a/en/docs/assets/img/api-policies/interceptor-policy.png b/en/docs/assets/img/api-policies/interceptor-policy.png
diff --git a/en/docs/assets/img/api-policies/mirror-request.png b/en/docs/assets/img/api-policies/mirror-request.png
diff --git a/en/docs/assets/img/api-policies/operation-level-policy-view.png b/en/docs/assets/img/api-policies/operation-level-policy-view.png
diff --git a/en/docs/assets/img/api-policies/redirect-request-response.png b/en/docs/assets/img/api-policies/redirect-request-response.png
diff --git a/en/docs/assets/img/api-policies/redirect-request.png b/en/docs/assets/img/api-policies/redirect-request.png
diff --git a/en/docs/assets/img/api-policies/remove-header.png b/en/docs/assets/img/api-policies/remove-header.png
diff --git a/en/docs/control-plane/api-management/api-policies/add-header.md b/en/docs/control-plane/api-management/api-policies/add-header.md
@@ -0,0 +1,8 @@
+The header modification functionality allows the addition, modification, and removal of headers in both requests and responses. This capability is useful for enhancing control and flexibility in API interactions, ensuring that specific requirements for incoming requests and outgoing responses are consistently met. This functionality is configured using the HTTPRoute filters `RequestHeaderModifier` and `ResponseHeaderModifier` filters, which specify how headers should be manipulated at various stages of the request and response lifecycle.
+
+To add headers to requests or responses for an API or an API operation, add the name of the header and the value you require as properties in the header policy, as shown below.
+
+[![Add Header](../../../assets/img/api-policies/add-header-policy.png)](../../../assets/img/api-policies/add-header-policy.png)
+
+!!! note
+    While interceptors can be used for header modification as well, it is recommended to use the Add Header and Remove Header policies for that scenario, and use Interceptor policies for more advanced use cases.
diff --git a/en/docs/control-plane/api-management/api-policies/api-policies-overview.md b/en/docs/control-plane/api-management/api-policies/api-policies-overview.md
@@ -0,0 +1,19 @@
+# Add API Policy to API in API Manager
+
+Policies generally enforce some business logic that needs to be executed on the Request or Response flow of an API invocation. A policy is a collection of rules that will be executed at the API Gateway. Using policies we can make API invocations undergo slight behavioural modifications before reaching the backend. In a similar manner, we can modify the API response a client receives.
+
+API Manager ships a default set of policies that cover most of the common use cases that you will need. You can attach policies to the API in the [API Manager publisher portal](https://am.wso2.com/publisher){:target="_blank"}.
+
+The list of supported policies are as follows.
+
+1. Request flow:
+    - [Add Header](./add-header.md){:target="_blank"}
+    - [Remove Header](./remove-header.md){:target="_blank"}
+    - [Call Interceptor Service](./interceptor-service.md){:target="_blank"}
+    - [Mirror Request](./mirror-request.md){:target="_blank"}
+    - [Redirect Request](./redirect-request.md){:target="_blank"}
+    - [Backend JWT](./backend-jwt.md){:target="_blank"}
+2. Response flow:
+    - [Add Header](./add-header.md){:target="_blank"}
+    - [Remove Header](./remove-header.md){:target="_blank"}
+    - [Call Interceptor Service](./interceptor-service.md){:target="_blank"}
diff --git a/en/docs/control-plane/api-management/api-policies/attaching-api-policies.md b/en/docs/control-plane/api-management/api-policies/attaching-api-policies.md
@@ -0,0 +1,44 @@
+## Attaching Policies
+
+Follow the instructions below to attach one or more default policies to an existing API.
+
+1. Sign in to the WSO2 API Publisher at [https://am.wso2.com/publisher](https://am.wso2.com/publisher){:target="_blank"}.
+
+2. Click on the API for which you want to attach policies to. Navigate to **API Configurations** → **Policies**.
+
+3. First let us consider the **API Level Policies** tab. You can attach any number of policies by dragging and dropping from the policy list to the dropzone appearing under the desired flow (i.e. request or response). Since these policies are attached to the API level, upon API invocation these policies are engaged regardless of the resource that was invoked.
+
+
+    !!! Note
+        API level policies will execute before operation level policies.
+
+[![API Policies](../../../assets/img/api-policies/api-level-policies.png)](../../../assets/img/api-policies/api-level-policies.png)
+
+4. Now let us consider the **Operation Level Policies** tab. Pick out the desired operation and flow to which you want to attach policies. Once that is decided, you can expand that API operation. At this point you will notice that by default the UI will open up the first API operation on initial page visit.
+
+5. Let’s attach a policy to the operation. Scroll down through the left side column of the UI and click on the operation. You should be able to see the below screen when the API operation is expanded.
+
+[![Operation Policies](../../../assets/img/api-policies/operation-level-policy-view.png)](../../../assets/img/api-policies/operation-level-policy-view.png)
+
+
+6. Drag the **Add Header** policy from the **Request** tab of the **Policy List** and drop that to the **Request Flow** dropzone of the first operation. You will notice a side panel appearing from the right hand side. Fill the required details using the values provided below. Then, click **Save**.
+
+| Field        | Sample Value |
+| ------------ | ------------ |
+| Header Name  | Foo          |
+| Header Value | Bar          |
+
+!!! Note
+    You can optionally use the **Apply to all** resources option to attach the same policy to all the resources. This will attach the same policy to all the API operations along with the values you entered to configure the policy (if any). It is important to note that if the policy was applied to the Request Flow, it will only be applied to all the request flows of all operations.
+
+7. Now that we have saved the dropped policy, you should be able to see the attached **Add Header** policy (depicted with the initials `AH`).
+
+[![Add Header](../../../assets/img/api-policies/attached-add-header.png)](../../../assets/img/api-policies/attached-add-header.png)
+
+8. If you click on this newly attached **AH** (i.e. Add Header) policy, you should still be able to view/edit values that you entered initially.
+
+[![Add Header](../../../assets/img/api-policies/add-header-policy.png)](../../../assets/img/api-policies/add-header-policy.png)
+
+You can attach as many policies as you want for the operation.
+
+9. Finally, when you are satisfied with the dragged and dropped policies, you can go ahead and click on the **Save** button at the bottom of the page. Note that if you do not click on save, none of the dropped policies will be saved to the API.
diff --git a/en/docs/control-plane/api-management/api-policies/backend-jwt.md b/en/docs/control-plane/api-management/api-policies/backend-jwt.md
@@ -0,0 +1,28 @@
+# Passing End User Attributes to the Backend
+
+There can be scenarios where a backend service needs to make different decisions or respond with different data, depending on the application end-user that consumes an API. To achieve this the backend service needs to have access to the respective end-user's data at the time an API call takes place.
+
+This can be facilitated by the Gateway by sending the end user attributes that are defined in the respective user store, in a JWT via an HTTP header, to the backend service when the API call is being forwarded.
+
+## How does it work?
+
+The backend JSON Web Token (JWT) contains the claims that are transferred between two parties, such as the end-user and the backend. A claim is an attribute of the user that is mapped to the underlying user store. A set of claims is referred to as a dialect (e.g., http://wso2.org/claims).
+
+If you enable backend JWT generation in the Gateway, each API request will carry a digitally signed JWT, which is in the following format to the backend service.
+
+`{token header}.{claims list}.{signature}`
+
+When the request goes through the Gateway, the backend JWT is appended as a transport header to the outgoing message. The backend service fetches the JWT and retrieves the required information about the user, application, or token.
+
+To enable backend JWT for an API or an operation, you can add a policy as follows.
+
+[![Backend JWT](../../../assets/img/api-policies/backend-jwt.png)](../../../assets/img/api-policies/backend-jwt.png)
+
+The following values need to be added to the policy.
+
+| Field             | Description                                                                               |
+| ----------------- | ----------------------------------------------------------------------------------------- |
+| Encoding          | The encoding mechanism used to encode the Backend JWT.                                    |
+| Signing Algorithm | The signing algorithm used to sign the Backend JWT.                                       |
+| Header Name       | The name of the HTTP header to which the Backend JWT is attached and sent to the backend. |
+| Token TTL         | The expiry time of the Backend JWT.                                                       |
diff --git a/en/docs/control-plane/api-management/api-policies/interceptor-service.md b/en/docs/control-plane/api-management/api-policies/interceptor-service.md
@@ -0,0 +1,26 @@
+
+You can use interceptors to carry out transformations and mediation on the requests and responses. Request interceptor gets triggered before sending the request to the backend. Response interceptor gets triggered before responding to the client. Here, an interceptor is a separate microservice that handles the request, response, or both request and response transformations.
+
+When you have attached an Interceptor `APIPolicy` like above example to your `API`, then the request flow (`1`, `2`, `3`, and `4` numbered circles) and response flow (`5`, `6`, `7`, and `8` numbered circles) can be depicted as below.
+
+![Interceptors](../../../assets/img/api-management/api-policies/interceptors/interceptors-light.png#only-light)
+![Interceptors](../../../assets/img/api-management/api-policies/interceptors/interceptors-dark.png#only-dark)
+
+If you are an API developer, you can write a custom request/response interceptor microservice in any programming language of your choice by following [the Interceptor OpenAPI Definition](https://github.com/wso2/apk/blob/main/developer/resources/interceptor-service-open-api-v1.yaml){:target="_blank"}. Then you can provide the endpoint of the microservice to the Interceptor policy and then save and redeploy the API.
+
+## Configuring Interceptors
+
+Configuring an interceptor requires the following two steps.
+
+1. [Implement an interceptor microservice adhering to the Interceptor OpenAPI Definition](https://apim.docs.wso2.com/en/4.2.0/deploy-and-publish/deploy-on-gateway/choreo-connect/message-transformation/interceptor-microservice/interceptor-microservice/){:target="_blank"}
+For reference, a sample interceptor service for data conversion between application/json and application/xml data types with interceptor policy CRs can be found here: [request-response-mediation-interceptors](https://github.com/wso2/apk/tree/main/samples/request-response-mediation-interceptors){:target="_blank"}
+
+2. Create the Interceptor Policy from the APIM Publisher window as follows.
+[![Interceptor Policy](../../../assets/img/api-policies/interceptor-policy.png)](../../../assets/img/api-policies/interceptor-policy.png)
+
+The following fields need to added.
+
+| Field Name          | Description                                                                                                                                                                                                     |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Service URL         | The endpoint of the interceptor microservice                                                                                                                                                                    |
+| Includes to payload | The content of the payload that must be sent to the interceptor. Possible values include: request_headers, request_body, request_trailer, response_headers, response_body, response_trailer, invocation_context |
diff --git a/en/docs/control-plane/api-management/api-policies/mirror-request.md b/en/docs/control-plane/api-management/api-policies/mirror-request.md
@@ -0,0 +1,9 @@
+Request mirroring allows traffic to be duplicated and sent to additional backends for testing and monitoring purposes. This feature is particularly useful for scenarios where you want to test changes or monitor the behavior of your application under different conditions without affecting the primary production or sandbox environment. The Request Mirror filter can mirror requests to different backends apart from the primary backend defined in the production or sandbox endpoints.
+
+The current implementation operates in a “fire and forget” manner, and only the response from the primary endpoint will be returned. This allows for the assessment of changes in a real-world environment without impacting the actual user experience. This method ensures that the production environment remains stable while providing insights into how updates or modifications would perform under actual load conditions.
+
+For request mirroring, add the URL you want the request to be mirrored to in the Mirror Request Policy as shown below.
+
+[![Mirror Request](../../../assets/img/api-policies/mirror-request.png)](../../../assets/img/api-policies/mirror-request.png)
+
+When this operation is invoked, the request will then be sent to the URL added in the policy and the backend URL.
diff --git a/en/docs/control-plane/api-management/api-policies/redirect-request.md b/en/docs/control-plane/api-management/api-policies/redirect-request.md
@@ -0,0 +1,17 @@
+
+Request redirection allows you to send clients to a different URL. This can be useful for changing old URLs to new ones or directing traffic based on specific conditions. Request redirection can be configured via the apk-conf file as follows.
+
+The redirect request policy requires two values:
+
+1. The URL to be shown in the location header in the response
+2. The status code to be shown in the response
+
+These values can be provided in the redirect request policy as follows.
+
+[![Redirect Request](../../../assets/img/api-policies/redirect-request.png)](../../../assets/img/api-policies/redirect-request.png)
+
+Once you have saved the above policy and redeployed the API, when you invoke the operation you added the redirect policy to, you will get a response similar to the following.
+
+[![Redirect Request Response](../../../assets/img/api-policies/redirect-request-response.png)](../../../assets/img/api-policies/redirect-request-response.png)
+
+The location header and the status code contain the values that were specified in the request redirect policy.
diff --git a/en/docs/control-plane/api-management/api-policies/remove-header.md b/en/docs/control-plane/api-management/api-policies/remove-header.md
@@ -0,0 +1,12 @@
+Web services may contain response headers with sensitive information. This header can be used to remove HTTP request headers from the responses for security reasons.
+
+To remove headers from requests or responses for an API or an API operation, add the name of the header to be removed as a property in the header policy, as shown below.
+
+[![Remove Header](../../../assets/img/api-policies/remove-header.png)](../../../assets/img/api-policies/remove-header.png)
+
+If the remove header policy is applied to the Request flow, the header will be removed from the request body and sent to the backend.
+
+If the remove header policy is applied to the Response flow, the header will be removed from the response body and sent back to the client.
+
+!!! note
+    While interceptors can be used for header modification as well, it is recommended to use the Add Header and Remove Header policies for that scenario, and use Interceptor policies for more advanced use cases.
diff --git a/en/docs/control-plane/api-management/control-plane-api-policies.md b/en/docs/control-plane/api-management/control-plane-api-policies.md
diff --git a/en/docs/create-api/create-and-attach-api-policies/api-policies-overview.md b/en/docs/create-api/create-and-attach-api-policies/api-policies-overview.md
@@ -14,7 +14,6 @@ There are a few levels where a Policy attachment can happen in APK resources.
 
 Attaching a policy to a specific level is descibed under each policy.
 
-
 ## Policy Execution Order
 
 When you have multiple policies attached in different levels policies, you need to be aware of in which order they are executed in runtime. The following table describes the execution order. The top one is executed first, and the bottom one is executed last.
@@ -47,9 +46,27 @@ Keep in mind that you cannot attach an API policy at two separate levels simulta
 
 When you attach a policy at the API-level, it will be applied globally to all the operations that correspond to the API. However, when you attach a policy at an operation level, it will only be applicable locally to a specific operation.
 
+## Supported API Policies
+
+The following API policies are supported in APK.
+
+- Interceptor Services
+- Backend JWT 
+- CORS
+- Header Modification
+- Request Redirection
+- Request Mirroring
+
+For more complex requirements that go beyond default policies, consider using **interceptor services**. These services enable you to:
+
+- Implement custom logic for request and response processing.
+- Apply transformations, validations, or enhancements based on specific use cases.
+
 ## What's Next?
 
-- [Learn to attach API Policies for Interceptor Services](./interceptors/interceptors-overview.md)
-- [Learn to attach API Policies for Backend JWT Token Manipulation](./backend-jwt-token-manipulation/overview.md)
-- [Learn to attach API Policies for CORS](./cors/enable-cors-via-rest-api.md)
-
+- [Learn to attach API Policies for Interceptor Services](./interceptors/interceptors-overview.md){:target="_blank"}
+- [Learn to attach API Policies for Backend JWT Token Manipulation](./backend-jwt-token-manipulation/overview.md){:target="_blank"}
+- [Learn to attach API Policies for CORS](./cors/enable-cors-via-rest-api.md){:target="_blank"}
+- [Learn to attach API Policies for Header Modification](./header-modifier-filters/overview.md){:target="_blank"}
+- [Learn to attach API Policies for Request Redirection](./redirect-request-filters/redirect-request-via-rest-api.md){:target="_blank"}
+- [Learn to attach API Policies for Request Mirroring](./mirror-request-filters/overview.md){:target="_blank"}
diff --git a/...e-api/create-and-attach-api-policies/backend-jwt-token-manipulation/overview.md b/...e-api/create-and-attach-api-policies/backend-jwt-token-manipulation/overview.md
@@ -1,6 +1,5 @@
 # Passing End User Attributes to the Backend
 
-
 There can be scenarios where a backend service needs to make different decisions or respond with different data, depending on the application end-user that consumes an API. To achieve this the backend service needs to have access to the respective end-user's data at the time an API call takes place.
 
 This can be facilitated by the Gateway by sending the end user attributes that are defined in the respective user store, in a JWT via an HTTP header, to the backend service when the API call is being forwarded.
@@ -15,41 +14,6 @@ If you enable backend JWT generation in the Gateway, each API request will carry
 
 When the request goes through the Gateway, the backend JWT is appended as a transport header to the outgoing message. The backend service fetches the JWT and retrieves the required information about the user, application, or token.
 
-## Sample JWT
-
-The following is an example of a JWT:
-
-``` java
-{
-    "typ":"JWT",
-    "alg":"NONE"
-    }{
-    "iss":"wso2.org/products/am",
-    "exp":1345183492181,
-    "http://wso2.org/claims/subscriber":"admin",
-    "http://wso2.org/claims/applicationname":"app2",
-    "http://wso2.org/claims/apicontext":"/placeFinder",
-    "http://wso2.org/claims/version":"1.0.0",
-    "http://wso2.org/claims/tier":"Silver",
-    "http://wso2.org/claims/enduser":"sumedha"
-    }
-```
-
-The above JSON Web Token (JWT) contains the following information.
-
-**JWT Header :** The header section declares that the encoded object is a JWT access token and the JWT is in plain text, that is not signed using any encryption algorithm.
-
-**JWT Claims set :**
-
--   `"iss"` - The issuer of the JWT
--   `"exp"` - The token expiration time
--   `"http://wso2.org/claims/subscriber"` - Subscriber to the API, usually the app developer
--   `" http://wso2.org/claims/applicationname"` - Application through which API invocation is done
--   `" http://wso2.org/claims/apicontext"` - Context of the API
--   `" http://wso2.org/claims/version "` - API version
--   `" http://wso2.org/claims/tier"` - Tier/price band for the subscription
--   `" http://wso2.org/claims/enduser"` - End-user of the app who's action invoked the API
-
 You can configure backend JWT in two ways.
 
 1. <a href="../../backend-jwt-token-manipulation/backend-jwt-token-manipulation-via-rest-api" target="_blank">Using the APK Conf file</a>

diff --git a/...cs/create-api/create-and-attach-api-policies/mirror-request-filters/overview.md b/...cs/create-api/create-and-attach-api-policies/mirror-request-filters/overview.md
@@ -6,5 +6,5 @@ The current implementation operates in a “fire and forget” manner, and only
 
 Request mirroring can be done in one of two ways.
 
-1. Via REST API (using the APK-Conf file).
-2. Via CRs.
+1. [Via REST API (using the APK-Conf file)](./mirror-request-via-rest-api.md){:target="_blank"}.
+2. [Via CRs](./mirror-request-via-crs.md){:target="_blank"}.
diff --git a/...te-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md b/...te-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md
@@ -1,4 +1,4 @@
-# Request Redirection via REST API
+# Request Redirection via CRs
 
 Request redirection allows you to send clients to a different URL. This can be useful for changing old URLs to new ones or directing traffic based on specific conditions. Request redirection can be configured via Kubernetes CRs as follows.