Configuring the Websocket Upgrade policy for DataPower API Gateway

Follow these steps to configure the Websocket Upgrade policy for DataPower® API Gateway in the assembly user interface.

1. In the navigation pane, click Develop, then select the APIs tab.
   The Develop page opens.
2. Click the title of the API that you want to work with, or create a new API.
3. Select the Gateway tab, then click Policies in the navigation pane.
   For more information about working with the assembly editor for an API, see The assembly editor.
4. Find the Websocket Upgrade policy in the palette, and drag the policy onto your canvas.
5. Specify the following properties.

   Table 1. Websocket Upgrade policy properties

   Property label	Required	Description	Data type
   Title	No	The title of the policy. The default value is websocket-upgrade.	string
   Description	No	A description of the policy.	string
   URL	Yes	Specify the URL to be invoked.	string
   TLS Profile	No	Specifies a TLS profile to use for the secure transmission of data.	string
   Timeout	No	The time to wait before a reply back from the endpoint (in seconds). The default value is 60.	integer
   Follow redirects	No	Specifies the behavior if the back-end server returns the HTTP status code 301 Moved Permanently. If you select this check box, the invoke policy follows the URL redirection by making a further call to the URL specified in the Location header in the response. If you clear this check box, the invoke saves the 301 status code and the API call is considered to be complete. Note: The follow-redirect property is supported only by the DataPower API Gateway. If you are using the DataPower Gateway (v5 compatible), the invoke always follows the URL redirection; the proxy policy (not supported by the DataPower API Gateway) saves the 301 status code and completes the API call without following the URL redirection.	boolean
   Username	No	The username to use for HTTP Basic authentication.	string
   Password	No	The password to use for HTTP Basic authentication.	string
   Inject proxy headers	No	If you select this check box, the invoke policy injects the X-Forwarded-For, X-Forwarded-To, X-Forwarded-Host, and X-Forwarded-Proto headers to the request that is sent to the target URL. The check box is cleared by default.	boolean
   Decode Request Params	No	If you select this check box, any request parameters that are referenced by a variable definition on the target URL of the invoke policy are URL-decoded. The check box is cleared by default.	boolean
   Queryparam encode	No	If you select this check box, all "+" characters in the query parameter values of the target URL are encoded to %2F. The check box is cleared by default.	boolean
   Header control	No	Specifies the headers in message.headers that you want to copy to the target URL. To prevent headers from being copied, complete the following steps: Select Blocklist. Click Add blocklist. In the empty field that is displayed, enter the header name. To add further headers, repeat the previous steps. To specify headers that you want to be copied, complete the following steps: Select Allowlist. Click Add allowlist. In the empty field that is displayed, enter the header name. To add further headers, repeat the previous steps. The values that you specify are in regular expression format. For example, to specify the Content-Type header, enter ^Content-Type$ By default, Blocklist is selected, with no blocklist entries, meaning that all headers are copied.	string
   Parameter control	No	Specifies the parameters in the incoming request that you want to be copied to the target URL. To prevent parameters from being copied, complete the following steps: Select Blocklist. Click Add blocklist. In the empty field that is displayed, enter the parameter name. To add further parameters, repeat the previous steps. To specify parameters that you want to be copied, complete the following steps: Select Allowlist. Click Add allowlist. In the empty field that is displayed, enter the parameter name. To add further parameters, repeat the previous steps. The values that you specify are in regular expression format. For example, if the incoming request is http://apigw/org/sandbox/petstore/base?petid=100&display=detailed and you specify a white list entry of ^petid$, the target URL at run time will be http://myhost/mypath?storeid=3&petid=100 By default, Allowlist is selected, with no allowlist entries, meaning that no parameters are copied.	string
   Request assembly	No	The request processing assembly. For details on configuring an assembly in the execute section, see execute. For example: request-assembly: execute . . . policy assembly . . .	object
   Response assembly	No	The response processing assembly. For details on configuring an assembly in the execute section, see execute. For example: response-assembly: execute . . . policy assembly . . .	object

6. Specify a version for the policy by clicking the Source icon , and completing the version section of the policy YAML. For example:

   execute:
     - websocket-upgrade:
         version: 2.0.0
         title: websocket-upgrade
     ...

   You must specify a version for the policy that is compatible with the gateway that you are using. When the API is published, if the version is incompatible with the gateway, a validation error is thrown that specifies the available versions.
7. Click Save.