invoke

Use the invoke policy to call an API.

Gateway support

Table 1. Table showing which gateways support this policy, and the corresponding policy version
Gateway	Policy version
DataPower® Gateway (v5 compatible)	1.0.0
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 Invoke.

About

Note:

The Invoke policy does not support responses with multipart form data, that is, when the response is set to Content-Type: multipart/related.
The Invoke policy always uses chunked encoding, which is not supported by the HTTP 1.0 protocol.

The invoke policy has the following format:

- invoke:
  version: version
  title: title
  description: description
  target-url: URL_of_target_API
  tls-profile: TLS_profile_to_be_used
  verb: method_type
  timeout: timeout_value_in_seconds
  compression: is_data_to_be_compressed
  username: username_if_authentication_required
  password: password_if_authentication_required
  output: location_of_the_invoke_result
  cache-key: unique_identifier_of_the_document_cache_entry
  cache-response: cache_behavior
  cache-putpost-response: response_caching_behavior
  cache-ttl: cache_time_to_live
  inject-proxy-headers: are_proxy_headers_sent_to_target_url
  decode-request-params: are_request_parameters_decoded
  encode-plus-char: are_plus_characters_encoded
  keep-payload: is_payload_sent_on_delete
  use-http-10: are_transactions_restricted_to_http_1.0
  chunked-uploads: are_chunked_encoded_documents_sent_to_the_server
  header-control:
        .
        .
        .
    headers_to_copy_to_target_url
        .
        .
        .
  parameter-control:
        .
        .
        .
    parameters_to_copy_to_target_url
        .
        .
        .
  follow-redirect: url_redirection_behavior
  stop-on-error: errors_that_stop_the_flow

Properties

The following table describes the properties of the invoke policy.

Table 2. Invoke policy properties
Property	Required	Description	Data type
version	Yes	The policy version number	string
title	No	A title for the policy.	string
description	No	A policy description.	string
target-url	Yes	The URL of the target API.	string
tls-profile	No	The TLS profile to be used.	string
verb	No	The operation method type. Valid values: GET POST PUT DELETE PATCH HEAD OPTIONS The default value is `GET`. However, if the property is omitted from the source, the HTTP method from the incoming request is used.	string
timeout	No	The timeout value in seconds. The default value is `60`.	integer
compression	No	Specifies whether data is to be compressed by using compress before it is uploaded. The default value is `false`.	boolean
username	No	The user name, if authentication is required.	string
password	No	The password, if authentication is required.	string
output	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 output property blank, do not supply the value `message`.	string
cache-key	No	Specifies the unique identifier of the document cache entry.	string
cache-response	No	The cache response type. Valid values: `protocol`: The cache behavior is defined by the Cache-Control headers on the request and response. `no-cache`: Specifies that there is no caching. However, if the document is already in the cache, the document is retrieved from the cache. `time-to-live`: Specifies that the response stays in the cache for the specified time. The default value is `protocol`.	string
cache-putpost-response	No	Specifies whether to cache the response from POST and PUT requests. Caching the response from POST and PUT requests can reduce server load and reduce latency in the response to the client request. The default value is `false`.	boolean
cache-ttl	No	Specifies the amount of time in seconds that the response stays in the cache. Applies only if the property cache-response is set to `time-to-live`. Enter a value in the range 5 - 31708800. The default value is `900`.	integer
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 t`target-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
keep-payload	No	When set to true, the invoke policy sends a payload on an `HTTP DELETE` method. The default value is `false`.	boolean
use-http-10 (policy version 2.0.0 only)	No	When set to true, HTTP transactions are restricted to version 1.0. The default value is `false`.	boolean
chunked-uploads	No	If you set this property to `true`, 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 default value is `true`. Note: Chunked encoding is not supported by the HTTP 1.0 protocol.	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 `blacklist`, 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 `whitelist`, 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: blacklist values: []` See header-control examples	string
`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 `blacklist`, the `values` property lists the parameters that you don't want to be copied. If the `type` property is set to `whitelist`, 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: whitelist values: []` See parameter-control examples	string
follow-redirect	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
stop-on-error	No	List the errors that, if thrown during the policy execution, cause the 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 specified for the Stop on error property, or if the error thrown is not one of the specified errors, the policy execution is allowed to complete, and the assembly flow continues.	string

Example

- 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
    verb: POST
    timeout: 60
    compression: false 
    username: MyUser
    password: MyPassword
    stop-on-error:
      - ConnectionError
      - OperationError

`header-control` examples

# copy all headers to the target URL

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: blacklist
      values: []

# copy all headers except X-Client-ID and Content-Type

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: blacklist
      values:
        - ^X-Client-ID$
        - ^Content-Type$

# copy no headers

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: whitelist
      values: []

# copy only the Content-Type header

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: whitelist
      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: whitelist
      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: whitelist
      values:
        - ^petid$