Configuring the Invoke policy for DataPower API Gateway

Follow these steps to configure the Invoke 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 definition that you want to work with.
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 Invoke policy in the palette, and drag the policy onto your canvas.
5. Specify the following properties.

   Table 1. Invoke policy properties

   Property label	Required	Description	Data type
   Title	Yes	The title of the policy. The default value is invoke.	string
   Description	No	A description of the policy.	string
   URL	Yes	Specifies a URL for the target service. For a SOAP API, a URL is added by default. Where possible, the Invoke URL value is pre-supplied from information that is defined in the imported WSDL.	string
   Backend type	No	Select one of the following options to determine how the payload is sent to the backend. Detect Detect the message type and send the payload to the backend accordingly. XML Package the payload as XML and send. If the message type is not XML, the operation fails. JSON Package the payload as JSON and send. If the message type is not JSON, the operation fails. Binary Package the payload as binary and send, regardless of the message type. GraphQL Package the payload as GraphQL and send. If the message type is not GraphQL, the operation fails. The default value is Detect.	string
   GraphQL send type(policy version 2.2.0 and later)	Yes, if Backend type is set to GraphQL or Detect, and HTTP Method is set to POST or Keep	Select one of the following values to determine how the GraphQL payload is sent to the back end. Detect Detect the message type and send the payload to the back end accordingly. GraphQL Package the payload as GraphQL and send. If the message type is not GraphQL, the operation fails. JSON Package the payload as JSON and send. If the message type is not GraphQL, the operation fails. Note: GraphQL send type is supported only if Backend type is set to GraphQL or Detect, and HTTP Method is set to POST or Keep.	string
   TLS profile	No	Specifies a TLS profile to use for the secure transmission of data.	string
   Timeout	Yes	The time to wait before a reply 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 checkbox, 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 checkbox, 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
   HTTP Method	Yes	The HTTP method to use for the Invoke. The following values are valid. Keep GET POST PUT DELETE PATCH HEAD OPTIONS The default value is GET. However, if set to Keep, or the property is removed from the source, the HTTP method from the incoming request is used.	string
   HTTP Version (policy version 2.1.0 and later)	Yes	The HTTP version that will be used when connecting to the backend server. Select one of the following values. HTTP/1.0 HTTP/1.1 HTTP/2 The default value is HTTP/1.1.	string
   HTTP/2 Required (policy version 2.1.0 and later)	No	Select this checkbox to require that the server selects HTTP/2 during a TLS connection, otherwise the DataPower API Gateway rejects the connection and fails the request. For a non-TLS connection, a warning is logged stating that the requirement can't be enforced. This setting applies only if HTTP Version is set to HTTP/2.	boolean
   Compression	No	Select this checkbox to enable Content-Encoding compression on upload. The checkbox is cleared by default.	boolean
   Cache Type	No	The cache type determines whether to cache documents, honoring or overriding the HTTP Cache Control directives received in the response from the target URL. This property takes effect only when a response is received, otherwise the policy always returns the non-expired response that was previously saved in cache. Valid values are: Protocol The cache behavior is determined by the Cache-Control headers on the response, in accordance with RFC 7234. To optimize performance, if the gateway receives more than one request for a resource that is not in the cache but could be cached when the response from the target URL is received, the gateway sends only one request to the target URL; the remaining requests are not processed until the response from the first request has been received and the cache behavior has been determined from this response. If the response indicates that caching is possible, the gateway responds to all waiting requests with the cached resource. If the response indicates that caching is not possible, the gateway sends all waiting requests to the target URL. Use this option only if you expect that responses from the target URL can be cached, in which case it should improve performance and limit the demand on the target URL. If, however, the target URL never indicates that the gateway should cache its response, performance might be impaired when compared to the No Cache option. No Cache Responses from the target URL are not cached on the gateway regardless of any caching headers returned. In this case, every request from the client is sent to the target URL. Use this option if you do not want to cache any of the backend responses on the gateway, or if it is unlikely that a response from the target URL will allow caching through the Cache-Control header settings. Time to Live This option is similar to the Protocol option except it allows you to specify the amount of time that you want the successful response from the invoke or proxy to remain in the cache. Use this option only if you expect that responses from the target URL can be cached. The default value is Protocol.	string
   Time to Live	No	Specifies the amount of time in seconds that the response stays in the cache. Applies only if the property Cache type is set to Time to Live. Enter a value in the range 5 - 31708800. The default value is 900.	integer
   Cache key	No	Specifies the unique identifier of the document cache entry. If omitted, the entire URL string is used as the key.	string
   Allow WebSocket Upgrade (policy version 2.1.0 and later)	No	Select this checkbox to allow an HTTP or HTTPS connection to be upgraded to the WebSocket protocol if the request received by the corresponding HTTP or HTTPS handler on the DataPower API Gateway uses WebSocket (ws) or WebSocket Secure (wss). Note: This setting is available only for GraphQL APIs. The Allow WebSocket Upgrade setting is deprecated. To allow WebSocket upgrade requests that can manage API processing data, define an assembly WebSocket upgrade policy. For more information, see Websocket Upgrade.	boolean
   Inject proxy headers	No	If you select this checkbox, 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 checkbox is cleared by default.	boolean
   Decode Request Params	No	If you select this checkbox, any request parameters that are referenced by a variable definition on the target URL of the invoke policy are URL-decoded. The checkbox is cleared by default.	boolean
   Queryparam Encode	No	If you select this checkbox, all "+" characters in the query parameter values of the target URL are encoded to %2F. The checkbox is cleared by default.	boolean
   Keep Payload	No	If you select this checkbox, the invoke policy sends a payload on an HTTP DELETE method. The checkbox is cleared by default.	boolean
   Restrict to HTTP 1.0 (policy version 2.0.0 only)	No	If you select this checkbox, HTTP transactions are restricted to version 1.0. The check box is cleared by default.	boolean
   Allow chunked uploads	No	If you select this checkbox, chunked-encoded documents are sent to the server. When the HTTP 1.1 protocol is used, the body of the document can be delimited by either Content-Length or chunked encoding. While all servers can interpret Content-Length, many applications fail to understand chunked-encoded documents. For this reason, Content-Length is the standard method. The use of Content-Length interferes with the ability of the DataPower Gateway to fully stream. If you must stream full documents to the target server, enable this property. When enabled, the server must be RFC 2616 compatible. Unlike all other HTTP 1.1 features that can be negotiated down at run time, you must know beforehand that the target server is RFC 2616 compatible. The check box is selected by default. Note: Chunked encoding is not supported by the HTTP 1.0 protocol.	boolean
   Persistent Connection (policy version 2.3.0 and later)	No	Select this checkbox to enable HTTP persistent connections, allowing connection re-use. The checkbox is selected 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
   Stop on error	No	Select the errors that, if thrown during the policy execution, cause the assembly flow to stop. If there is a catch flow configured for the error, it is triggered to handle the error thrown. If an error is thrown and there are no errors selected for the Stop on error setting, or if the error thrown is not one of the selected errors, the policy execution is allowed to complete, and the assembly flow continues.	string
   Response object variable	No	The name of a variable that will be used to store the response data from the request. By default, the invoke response, that is the body, headers, statusCode and statusMessage, is saved in the variable message. Use this property to specify an alternate location to store the invoke response. This variable can then be referenced in other actions, such as Map. Note: If you want the response to be saved in message, leave the Response object variable property blank, do not supply the value message.	string

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

   execute:
     - invoke:
         version: 2.0.0
         title: invoke
     ...

   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.

- invoke:
    version: 2.0.0
    title: get the account status
    target-url: https://example.com/accounts/{id}?status={status}
    cache-response: time-to-live
    cache-putpost-response: true
    tls-profile: MyTLSProfile:1.0.0
    verb: POST
    timeout: 60
    compression: false 
    username: MyUser
    password: MyPassword
    stop-on-error:
      - ConnectionError
      - OperationError