websocket-upgrade

Use the websocket-upgrade policy to process API requests and responses through a WebSocket connection.

Gateway support

Table 1. Table showing which gateways support this policy, and the corresponding policy version
Gateway Policy version
DataPower® API Gateway 2.0.0

This topic describes how to configure the policy in your OpenAPI source; for details on how to configure the policy in the assembly user interface, see Websocket Upgrade.

The websocket-upgrade policy has the following format:
- websocket-upgrade:
  version: version
  title: title
  description: description
  target-url: URL_of_target_API
  tls-profile: TLS_profile_to_be_used
  timeout: timeout_value_in_seconds
  follow-redirects: redirect_behavior_on_301_error
  username: username_if_authentication_required
  password: password_if_authentication_required
  inject-proxy-headers: are_proxy_headers_sent_to_target_url
  decode-request-params: are_request_parameters_decoded
  encode-plus-char: are_plus_characters_encoded
  header-control:
        .
        .
        .
    headers_to_copy_to_target_url
        .
        .
        .
  parameter-control:
        .
        .
        .
    parameters_to_copy_to_target_url
        .
        .
        .

Properties

Table 2. websocket-upgrade policy properties
Property Required Description Data type
version Yes The policy version number. string
title No The title of the policy. string
description No A description of the policy. string
target-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 this property is set to true, the invoke policy follows the URL redirection by making a further call to the URL specified in the Location header in the response. If this property is set to false, 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 When set to true, 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 ttarget-url.

The default value is false.

 boolean
decode-request-params No When set to true, any request parameters that are referenced by a variable definition on the target-url of the invoke policy are URL-decoded.

The default value is false.

 boolean
encode-plus-char No When set to true, all "+" characters in the query parameter values of the target-url are encoded to %2F.

The default value is false.

 boolean 
header-control:
  type
  values
 No Specifies the headers in message.headers that you want to copy to the target URL.

If the type property is set to blocklist, the values property lists the headers that you don't want to be copied. If the values property is empty then all headers are copied.

If the type property is set to allowlist, the values property lists the headers that you want to be copied.

The items that are listed in the values property are in regular expression format. The values are not case-sensitive. The default value of the header-control property is
header-control:
  type: blocklist
  values: []

See header-control examples

 object 
parameter-control:
  type
  values
 No Specifies the parameters in the incoming request that you want to be copied to the target URL.

If the type property is set to blocklist, the values property lists the parameters that you don't want to be copied.

If the type property is set to allowlist, the values property lists the parameters that you want to be copied. If the values property is empty then no parameters are copied.

The items that are listed in the values property are in regular expression format. The values are not case-sensitive. The default value of the parameter-control property is
parameter-control:
  type: allowlist
  values: []

See parameter-control examples

 object 
request-assembly:
  execute
     .
     .
     .
    policy assembly
     .
     .
     .
 No The request processing assembly. For details on configuring an assembly in the execute section, see execute. object 
response-assembly:
  execute
     .
     .
     .
    policy assembly
     .
     .
     .
 No The response processing assembly. For details on configuring an assembly in the execute section, see execute. object

Example

- websocket-upgrade:
  version: 2.0.0
  title: websocket-upgrade
  timeout: 60
  target-url: 'https://my.websocket.upgrade.com'
  secure-gateway: false
  follow-redirects: true
  inject-proxy-headers: true
  decode-request-params: false
  encode-plus-char: true
  response-assembly:
    execute:
      - parse:
          version: 2.0.0
          title: parse
          parse-settings-reference:
            default: apic-default-parsesettings
          description: Parse the response from the backend server

header-control examples

# copy all headers to the target URL

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: blocklist
      values: []
# copy all headers except X-Client-ID and Content-Type

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: allowlist
      values:
        - ^X-Client-ID$
        - ^Content-Type$
# copy no headers

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: allowlist
      values: []
# copy only the Content-Type header

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: allowlist
      values:
        - ^Content-Type$

parameter-control examples

# copy no request parameters to the target URL

- invoke:
    target-url: http://myhost/path?storeid=3
    parameter-control:
      type: allowlist
      values: []
# append the petid parameter to the target URL
# if the incoming request is http://apigw/org/sandbox/petstore/base?petid=100&display=detailed, 
# the target URL at runtime will be http://myhost/mypath?storeid=3&petid=100

- invoke:
    target-url: http://myhost/path?storeid=3
    parameter-control:
      type: allowlist
      values:
        - ^petid$