Add documentation for header modification

wso2 · Jul 5, 2024 · 4af66e6 · 4af66e6
1 parent 3f9ae08
commit 4af66e6
Show file tree

Hide file tree

Showing 3 changed files with 382 additions and 1 deletion.
diff --git a/en/docs/create-api/create-and-attach-api-policies/cors/enable-cors-via-rest-api.md b/en/docs/create-api/create-and-attach-api-policies/cors/enable-cors-via-rest-api.md
@@ -112,7 +112,8 @@ corsConfiguration:
     - "*"
 ```
 
-   Sample APK configuration content after the modification is shown below.
+Sample APK configuration content after the modification is shown below.
+
 ```
 name: "EmployeeServiceAPI"
 basePath: "/test"

diff --git a/...eate-and-attach-api-policies/header-modifier-filters/header-modifier-via-crs.md b/...eate-and-attach-api-policies/header-modifier-filters/header-modifier-via-crs.md
@@ -0,0 +1,188 @@
+# Header Modification via CRs
+
+This functionality enables the addition, modification, and removal of request and response headers for APIs. By customizing headers, you can enhance the control and flexibility of API interactions, ensuring that both incoming requests and outgoing responses meet specific requirements.
+
+### Step 1 - Get the CRs for the relevant API configuration
+
+Here, you can follow the steps in [Develop and Deploy a REST API via CRs](../../create-and-deploy-apis/rest/create-rest-api-using-crs.md) documentation and create the CRs to deploy an API from scratch. 
+
+Alternatively, you can generate the CRs for a given apk-conf file using the steps as detailed in [this section](../../../api-management-overview/create-api-using-crs.md)
+
+### Step 2 - Add the header modification filters to the HTTPRoute CR
+
+Header modification can be done using an HTTPRoute filter as follows.
+
+```
+  - type: "RequestHeaderModifier"
+    requestHeaderModifier:
+    set:
+        - name: "Set-Request-Header"
+          value: "Set-Value"
+    add:
+        - name: "Add-Request-Header"
+          value: "Added-Value"
+    remove:
+        - "Remove-Request-Header"
+```
+
+This filter does the following modifications to the request headers.
+
+1. Update the header named "Set-Request-Header" with the value "Set-Value".
+2. Adds a header named "Add-Request-Header" with the value "Added-Value".
+3. Removes the header named "Remove-Request-Header".
+
+!!! Note
+    - By replacing the type with "ResponseHeaderModifier", the modifications can be done to the response. 
+    - Both RequestHeaderModifier and ResponseHeaderModifier can be added to the same rule.
+
+An HTTPRoute with the header modifiers is given below.
+
+```
+---
+apiVersion: "gateway.networking.k8s.io/v1beta1"
+kind: "HTTPRoute"
+metadata:
+  name: "production-httproute"
+spec:
+  hostnames:
+    - "default.gw.wso2.com"
+  rules:
+    - matches:
+        - path:
+            type: "RegularExpression"
+            value: "/employee"
+          method: "GET"
+      filters:
+        - type: "URLRewrite"
+          urlRewrite:
+            path:
+              type: "ReplaceFullPath"
+              replaceFullPath: "/employee"
+        - type: "RequestHeaderModifier"
+          requestHeaderModifier:
+            set:
+              - name: "Set-Request-Header"
+                value: "Test-Value"
+            add:
+              - name: "Test-Request-Header"
+                value: "Test-Value"
+            remove:
+              - "Remove-Header"
+      backendRefs:
+        - group: "dp.wso2.com"
+          kind: "Backend"
+          name: "api-backend"
+```
+
+Sample configurations for each of them have been provided under the [Sample Configurations](#sample-configurations) section.
+
+### Step 3 - Deploy the API in APK
+You can deploy the CRs using `kubectl apply -f . -n <namespace>`
+
+### Sample Configurations
+
+#### Request Header Modification
+
+##### 1. Add Request Header
+
+```
+rules:
+ - matches:
+     - path:
+         type: "RegularExpression"
+         value: "/employee"
+       method: "GET"
+   filters:
+     - type: "RequestHeaderModifier"
+       requestHeaderModifier:
+         add:
+           - name: "Add-Request-Header"
+             value: "Added-Value"
+```
+
+##### 2. Update Request Header
+
+```
+rules:
+ - matches:
+     - path:
+         type: "RegularExpression"
+         value: "/employee"
+       method: "GET"
+   filters:
+     - type: "RequestHeaderModifier"
+       requestHeaderModifier:
+         add:
+           - name: "Set-Request-Header"
+             value: "Set-Value"
+```
+
+##### 3. Remove Request Header
+
+```
+rules:
+ - matches:
+     - path:
+         type: "RegularExpression"
+         value: "/employee"
+       method: "GET"
+   filters:
+     - type: "RequestHeaderModifier"
+       requestHeaderModifier:
+         add:
+           - name: "Add-Request-Header"
+             value: "Added-Value"
+```
+
+#### Response Header Modification
+
+##### 1. Add Request Header
+
+```
+rules:
+ - matches:
+     - path:
+         type: "RegularExpression"
+         value: "/employee"
+       method: "GET"
+   filters:
+     - type: "ResponseHeaderModifier"
+       requestHeaderModifier:
+         add:
+           - name: "Add-Request-Header"
+             value: "Added-Value"
+```
+
+##### 2. Update Request Header
+
+```
+rules:
+ - matches:
+     - path:
+         type: "RegularExpression"
+         value: "/employee"
+       method: "GET"
+   filters:
+     - type: "ResponseHeaderModifier"
+       requestHeaderModifier:
+         add:
+           - name: "Set-Request-Header"
+             value: "Set-Value"
+```
+
+##### 3. Remove Response Header
+
+```
+rules:
+ - matches:
+     - path:
+         type: "RegularExpression"
+         value: "/employee"
+       method: "GET"
+   filters:
+     - type: "ResponseHeaderModifier"
+       requestHeaderModifier:
+         add:
+           - name: "Add-Request-Header"
+             value: "Added-Value"
+```
diff --git a/...and-attach-api-policies/header-modifier-filters/header-modifier-via-rest-api.md b/...and-attach-api-policies/header-modifier-filters/header-modifier-via-rest-api.md
@@ -0,0 +1,192 @@
+# Header Modification via APK Conf
+
+This functionality enables the addition, modification, and removal of request and response headers for APIs. By customizing headers, you can enhance the control and flexibility of API interactions, ensuring that both incoming requests and outgoing responses meet specific requirements.
+
+### Step 1 - Get the API configuration
+
+Here, you can follow the steps in [Create an API](../../../get-started/quick-start-guide.md) documentation and save this content into a file named `EmployeeService.apk-conf`. You can use this apk-conf file for the rest of this guide.
+
+### Step 2 - Add the header modification policy to the apk-conf file
+
+A sample header modification configuration is given below.
+
+```
+  - target: "/employee"
+    verb: "GET"
+    secured: false
+    scopes: []
+    operationPolicies:
+      request:
+        - policyName: AddHeader
+          policyVersion: v1
+          parameters:
+            headerName: "Test-Request-Header"
+            headerValue: "Test-Value"
+```
+
+This policy adds a header with the name "Test-Request-Header" and value "Test-Value" to the request sent to this particular path.
+
+The complete apk-conf file with this configuration is given below.
+
+```
+id: "header-modifier-api"
+name: "EmployeeServiceAPI"
+basePath: "/employees"
+version: "3.14"
+type: "REST"
+defaultVersion: false
+endpointConfigurations:
+    production:
+        endpoint: "https://httpbin.org/anything"
+operations:
+- target: "/employee"
+  verb: "GET"
+  secured: false
+  scopes: []
+  operationPolicies:
+    request:
+      - policyName: AddHeader
+        policyVersion: v1
+        parameters:
+          headerName: "Test-Request-Header"
+          headerValue: "Test-Value"
+- target: "/employee"
+    verb: "POST"
+    secured: true
+    scopes: []
+- target: "/employee/{employeeId}"
+    verb: "PUT"
+    secured: true
+    scopes: []
+- target: "/employee/{employeeId}"
+    verb: "DELETE"
+    secured: true
+    scopes: []
+```
+Similarly, you can do the following to both request and response headers.
+1. Add headers
+2. Update existing headers
+3. Remove headers
+
+Sample configurations for each of them have been provided under the [Sample Configurations](#sample-configurations) section.
+
+### Step 3 - Deploy the API in APK
+
+Refer to the [Deploy the API in APK](../../../get-started/quick-start-guide.md#deploy-the-api-in-apk) to deploy the API using APK configuration.
+
+### Step 4 - Generate an Acess Token
+
+Follow the [Generate Access Token](../../../develop-and-deploy-api/security/generate-access-token.md) documentation to generate an access token.
+
+### Step 5 - Invoke the API
+
+You can invoke the API using the following command.
+
+```
+curl --location 'https://default.gw.wso2.com:9095/employees/1.0/employee' \
+--header 'Host: default.gw.wso2.com' \
+--header 'Authorization: Bearer <accessToken>
+```
+
+Since this guide uses the [httpbin service](https://httpbin.org/anything) which echoes the request and all of its headers, when you invoke the API, you will see the header "Test-Request-Header" with the value "Test-Value".
+
+
+### Sample Configurations
+
+#### Request Header Modification
+
+##### 1. Add Request Header
+
+```
+- target: "/employee"
+ verb: "GET"
+ secured: false
+ scopes: []
+ operationPolicies:
+   request:
+     - policyName: AddHeader
+       policyVersion: v1
+       parameters:
+         headerName: "Header-Name"
+         headerValue: "Header-Value"
+```
+
+##### 2. Update Request Header
+
+```
+- target: "/employee"
+  verb: "GET"
+  secured: false
+  scopes: []
+  operationPolicies:
+    request:
+      - policyName: SetHeader
+        policyVersion: v1
+        parameters:
+          headerName: "Header-Name"
+          headerValue: "Header-Value"
+```
+
+##### 3. Remove Request Header
+
+```
+- target: "/employee"
+  verb: "GET"
+  secured: false
+  scopes: []
+  operationPolicies:
+    request:
+      - policyName: SetHeader
+        policyVersion: v1
+        parameters:
+          headerName: "Header-Name"
+```
+
+#### Response Header Modification
+
+##### 1. Add Response Header
+
+```
+- target: "/employee"
+  verb: "GET"
+  secured: false
+  scopes: []
+  operationPolicies:
+    response:
+      - policyName: AddHeader
+        policyVersion: v1
+        parameters:
+          headerName: "Header-Name"
+          headerValue: "Header-Value"
+```
+
+##### 2. Update Response Header
+
+```
+- target: "/employee"
+  verb: "GET"
+  secured: false
+  scopes: []
+  operationPolicies:
+    response:
+      - policyName: SetHeader
+        policyVersion: v1
+        parameters:
+          headerName: "Header-Name"
+          headerValue: "Header-Value"
+```
+
+##### 3. Remove Response Header
+
+```
+- target: "/employee"
+  verb: "GET"
+  secured: false
+  scopes: []
+  operationPolicies:
+    response:
+      - policyName: SetHeader
+        policyVersion: v1
+        parameters:
+          headerName: "Header-Name"
+```