invoke

Use the invoke policy to call an API.

Gateway support

Restriction: It is not possible to cache a request that includes the Authorization request header.

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 2.1.0 (DataPower API Gateway Version 10.0.1.1 or later) 2.2.0 (DataPower API Gateway Version 10.0.2.0 or later) 2.3.0 ( DataPower API Gateway Version 10.0.3.0 or later)

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

The invoke policy has the following format:

- invoke:
  version: version
  title: title
  description: description
  target-url: URL_of_target_API
  backend-type: how_payload_is_sent_to_backend
  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
  persistent-connection: are_persistent_connections_enabled
  header-control:
        .
        .
        .
    headers_to_copy_to_target_url
        .
        .
        .
  parameter-control:
        .
        .
        .
    parameters_to_copy_to_target_url
        .
        .
        .
  follow-redirects: 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
backend-type	No	Specify one of the following values 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 verb is set to `POST` or `keep`.	Specify 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 verb is set to `POST` or `keep`.	string
tls-profile	No	Specifies a TLS profile to use for the secure transmission of data. Note: If you want to edit the API in the source view, make sure that the tls-profile value follows this format: name:version. For instance, it should look like nameofmytlsclientprofile:1.0.0.	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 time to wait before a reply back from the endpoint (in seconds). The default value is `60`.	integer
http-version (policy version 2.1.0 and later)	Yes	The HTTP version that will be used when connecting to the backend server. Valid values: `HTTP/1.0` `HTTP/1.1` `HTTP/2`	string
http2-required (policy version 2.1.0 and later)	No	Set this property to `true` 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	Specifies whether data is to be compressed by using compress before it is uploaded. The default value is `false`.	boolean
username	No	The username to use for HTTP Basic authentication.	string
password	No	The password to use for HTTP Basic authentication.	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
websocket-upgrade (policy version 2.1.0 and later)	No	Set this property to `true` 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 property is available only for GraphQL APIs. The `websocket-upgrade` property 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
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
persistent-connection (policy version 2.3.0 and later)	No	Set this property to `true` to enable HTTP persistent connections, allowing connection re-use. The default value is `true`.	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
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:1.0.0
    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: blocklist
      values: []

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

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