From e76ef64140ce67f1d59d8cd34ba52bfa2de785c3 Mon Sep 17 00:00:00 2001 From: sgayangi Date: Mon, 8 Jul 2024 13:59:50 +0530 Subject: [PATCH] Add request redirection documentation --- .../create-api-using-crs.md | 2 +- .../header-modifier-via-crs.md | 7 +- .../header-modifier-via-rest-api.md | 126 ++++++++++++++++-- .../redirect-request-via-crs.md | 92 +++++++++++++ .../redirect-request-via-rest-api.md | 92 +++++++++++++ en/mkdocs.yml | 10 ++ 6 files changed, 312 insertions(+), 17 deletions(-) create mode 100644 en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md create mode 100644 en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-rest-api.md diff --git a/en/docs/api-management-overview/create-api-using-crs.md b/en/docs/api-management-overview/create-api-using-crs.md index 3ee4f3c4a..1b71ad50f 100644 --- a/en/docs/api-management-overview/create-api-using-crs.md +++ b/en/docs/api-management-overview/create-api-using-crs.md @@ -1,3 +1,3 @@ We support API management through a set of Custom Resources (CRs) that adhere to Kubernetes Gateway Specification. See [APK Kubernetes CRD Catalog]({{base_path}}/en/latest/catalogs/kubernetes-crds) for more information. -Additionally, our REST API flow can generate a set of CRs based on the API definitions provided through OpenAPI Specifications, Service Description Languages (SDLs), and APK configuration files. This flow is designed to streamline the API development process and reduce the manual effort required to create basic API related CRs. Follow steps mentions in [Generate APK Configuration File]({{base_path}}/en/latest/api-management-overview/tools-for-api-development/#option-2-generate-k8s-custom-resources-using-config-generator-tool-and-deploy-the-api-using-kubernetes-client) to generate APK configuration files. +Additionally, our REST API flow can generate a set of CRs based on the API definitions provided through OpenAPI Specifications, Service Description Languages (SDLs), and APK configuration files. This flow is designed to streamline the API development process and reduce the manual effort required to create basic API related CRs. Follow the steps mentioned in [Generate APK Configuration File]({{base_path}}/en/latest/api-management-overview/tools-for-api-development/#option-2-generate-k8s-custom-resources-using-config-generator-tool-and-deploy-the-api-using-kubernetes-client) to generate APK configuration files. diff --git a/en/docs/create-api/create-and-attach-api-policies/header-modifier-filters/header-modifier-via-crs.md b/en/docs/create-api/create-and-attach-api-policies/header-modifier-filters/header-modifier-via-crs.md index 65677c822..74acf84ee 100644 --- a/en/docs/create-api/create-and-attach-api-policies/header-modifier-filters/header-modifier-via-crs.md +++ b/en/docs/create-api/create-and-attach-api-policies/header-modifier-filters/header-modifier-via-crs.md @@ -6,7 +6,7 @@ This functionality enables the addition, modification, and removal of request an 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) +Alternatively, you can generate the CRs for a given apk-conf file using the steps as detailed in [this section]({{base_path}}/en/latest/api-management-overview/tools-for-api-development/#option-2-generate-k8s-custom-resources-using-config-generator-tool-and-deploy-the-api-using-kubernetes-client) ### Step 2 - Add the header modification filters to the HTTPRoute CR @@ -77,7 +77,10 @@ spec: 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 ` +You can deploy the API using the following command. Replace with the correct namespace. +``` +kubectl apply -f . -n +``` ### Sample Configurations diff --git a/en/docs/create-api/create-and-attach-api-policies/header-modifier-filters/header-modifier-via-rest-api.md b/en/docs/create-api/create-and-attach-api-policies/header-modifier-filters/header-modifier-via-rest-api.md index 63260253a..1ca45c97b 100644 --- a/en/docs/create-api/create-and-attach-api-policies/header-modifier-filters/header-modifier-via-rest-api.md +++ b/en/docs/create-api/create-and-attach-api-policies/header-modifier-filters/header-modifier-via-rest-api.md @@ -63,6 +63,7 @@ operations: secured: true scopes: [] ``` + Similarly, you can do the following to both request and response headers. 1. Add headers 2. Update existing headers @@ -74,7 +75,7 @@ Sample configurations for each of them have been provided under the [Sample Conf 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 +### Step 4 - Generate an access token Follow the [Generate Access Token](../../../develop-and-deploy-api/security/generate-access-token.md) documentation to generate an access token. @@ -90,25 +91,24 @@ curl --location 'https://default.gw.wso2.com:9095/employees/1.0/employee' \ 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 +#### Operation Level 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" + verb: "GET" + secured: false + scopes: [] + operationPolicies: + request: + - policyName: AddHeader + policyVersion: v1 + parameters: + headerName: "Header-Name" + headerValue: "Header-Value" ``` ##### 2. Update Request Header @@ -142,7 +142,7 @@ Since this guide uses the [httpbin service](https://httpbin.org/anything) which headerName: "Header-Name" ``` -#### Response Header Modification +#### Operation Level Response Header Modification ##### 1. Add Response Header @@ -190,3 +190,101 @@ Since this guide uses the [httpbin service](https://httpbin.org/anything) which parameters: headerName: "Header-Name" ``` +#### API Level Request Header Modification + +##### 1. Add Request Header + +``` +- target: "/employee" + verb: "GET" + secured: false + scopes: [] +apiPolicies: + request: + - policyName: AddHeader + policyVersion: v1 + parameters: + headerName: "Header-Name" + headerValue: "Header-Value" +``` + +##### 2. Update Request Header + +``` +- target: "/employee" + verb: "GET" + secured: false + scopes: [] +apiPolicies: + request: + - policyName: SetHeader + policyVersion: v1 + parameters: + headerName: "Header-Name" + headerValue: "Header-Value" +``` + +##### 3. Remove Request Header + +``` +- target: "/employee" + verb: "GET" + secured: false + scopes: [] +apiPolicies: + request: + - policyName: SetHeader + policyVersion: v1 + parameters: + headerName: "Header-Name" + +``` + +#### API Level Response Header Modification + +##### 1. Add Response Header + +``` +- target: "/employee" + verb: "GET" + secured: false + scopes: [] +apiPolicies: + response: + - policyName: AddHeader + policyVersion: v1 + parameters: + headerName: "Header-Name" + headerValue: "Header-Value" +``` + +##### 2. Update Response Header + +``` +- target: "/employee" + verb: "GET" + secured: false + scopes: [] +apiPolicies: + response: + - policyName: SetHeader + policyVersion: v1 + parameters: + headerName: "Header-Name" + headerValue: "Header-Value" +``` + +##### 3. Remove Response Header + +``` +- target: "/employee" + verb: "GET" + secured: false + scopes: [] +apiPolicies: + response: + - policyName: SetHeader + policyVersion: v1 + parameters: + headerName: "Header-Name" +``` \ No newline at end of file diff --git a/en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md b/en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md new file mode 100644 index 000000000..53bb93248 --- /dev/null +++ b/en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md @@ -0,0 +1,92 @@ +# Request Redirection via REST API + +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. + +### 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]({{base_path}}/en/latest/api-management-overview/tools-for-api-development/#option-2-generate-k8s-custom-resources-using-config-generator-tool-and-deploy-the-api-using-kubernetes-client) + +### Step 2 - Add the request redirection filters to the HTTPRoute CR + +A sample request redirection configuration for an HTTPRoute is given below. + +``` +filters: +- type: "RequestRedirect" + requestRedirect: + scheme: "https" + hostname: "httpbin.org" + path: + type: "ReplaceFullPath" + replaceFullPath: "/anything" + statusCode: 301 +``` + +This policy will redirect an incoming request to the GET /employee route with a 301 status code. + +The complete HTTPRoute with this configuration 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: "RequestRedirect" + requestRedirect: + scheme: "https" + hostname: "httpbin.org" + path: + type: "ReplaceFullPath" + replaceFullPath: "/anything" + statusCode: 301 + parentRefs: + - group: "gateway.networking.k8s.io" + kind: "Gateway" + name: "wso2-apk-default" + sectionName: "httpslistener" +``` + +!!! Note + An HTTPRoute rule that has a RequestRedirect filter cannot have a backendRef or a URLRewrite filter attached. + +### Step 3 - Deploy the API in APK + +You can deploy the API using the following command. Replace with the correct namespace. +``` +kubectl apply -f . -n +``` + +### Step 4 - Generate an access 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/employee/1.0/employee' \ +--header 'Host: default.gw.wso2.com' \ +--header 'Authorization: Bearer -I +``` + +Once you have invoked the above, you will see the 301 status code and the `Location` header containing the new URL. + +``` +HTTP/2 301 +location: https://httpbin.org/anything?id=1 +vary: Accept-Encoding +server: envoy +``` \ No newline at end of file diff --git a/en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-rest-api.md b/en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-rest-api.md new file mode 100644 index 000000000..2e089ba95 --- /dev/null +++ b/en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-rest-api.md @@ -0,0 +1,92 @@ +# Request Redirection via REST API + +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. + +### 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 request redirection policy to the apk-conf file + +A sample request redirection configuration is given below. + +``` +- target: "/employee" + verb: "GET" + secured: false + scopes: [] + operationPolicies: + request: + - policyName: RequestRedirect + policyVersion: v1 + parameters: + url: https://httpbin.org/anything + statusCode: 301 +``` + +This policy will redirect an incoming request to the GET /employee route with a 301 status code. + +The complete apk-conf file with this configuration is given below. + +``` +id: "redirect-request-api" +name: "EmployeeServiceAPI" +basePath: "/employee" +version: "1.0" +type: "REST" +defaultVersion: false +endpointConfigurations: + production: + endpoint: https://httpbin.org/anything +operations: +- target: "/employee" + verb: "GET" + secured: false + scopes: [] + operationPolicies: + request: + - policyName: RequestRedirect + policyVersion: v1 + parameters: + url: https://httpbin.org/anything + statusCode: 301 +- target: "/employee" + verb: "POST" + secured: true + scopes: [] +- target: "/employee/{employeeId}" + verb: "PUT" + secured: true + scopes: [] +- target: "/employee/{employeeId}" + verb: "DELETE" + secured: true + scopes: [] +``` +### 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 access 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/employee/1.0/employee' \ +--header 'Host: default.gw.wso2.com' \ +--header 'Authorization: Bearer -I +``` + +Once you have invoked the above, you will see the 301 status code and the `Location` header containing the new URL. + +``` +HTTP/2 301 +location: https://httpbin.org/anything?id=1 +vary: Accept-Encoding +date: Mon, 08 Jul 2024 08:05:57 GMT +server: envoy +``` \ No newline at end of file diff --git a/en/mkdocs.yml b/en/mkdocs.yml index c324eb744..3c14e4566 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -123,6 +123,16 @@ nav: - CORS: - Via REST API: create-api/create-and-attach-api-policies/cors/enable-cors-via-rest-api.md - Via CRs: create-api/create-and-attach-api-policies/cors/enable-cors-via-crs.md + - Header Modification: + - Via REST API: create-api/create-and-attach-api-policies/header-modifier-filters/header-modifier-via-rest-api.md + - Via CRs: create-api/create-and-attach-api-policies/header-modifier-filters/header-modifier-via-crs.md + - Request Mirroring: + - Overview: create-api/create-and-attach-api-policies/mirror-request-filters/overview.md + - Via REST API: create-api/create-and-attach-api-policies/mirror-request-filters/mirror-request-via-rest-api.md + - Via CRs: create-api/create-and-attach-api-policies/mirror-request-filters/mirror-request-via-crs.md + - Request Redirection: + - Via REST API: create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-rest-api.md + - Via CRs: create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md - Rate Limiting: - Overview: create-api/rate-limiting/rate-limiting-policy-overview.md - Simple Rate Limiting: