invoke

Use the invoke policy to call an API.

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 has the following format:

- invoke:
  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
  stop-on-error: 
    - stop_on_error_type

From IBM® API Connect V5.0.8.0 and beyond, users might notice that the last invoke in their policy is replaced by a proxy. The replacement is sometimes done automatically by the IBM API Connect DataPower® Gateway to improve performance. The proxy is functionally equivalent to the invoke, but the API caller might notice the following differences when proxy is used.

If the HTTP request made by the invoke or proxy gets a redirect (3xx) response:
- invoke returns the response from following the redirect response.
- proxy does not follow 3xx responses, and the redirect response is returned.
The API Connect test tool shows that proxy was used, but invoke appears in the Analytics latency records.
The response from the proxy can contain different whitespace or escaping than a response from invoke. Despite the differences in the response, it is still valid.

Note that a proxy policy ignores the Stop on error property, and that a replacement with a proxy does not occur if you have configured any catches on the invoke policy. For more information about the proxy policy, see proxy. If you want to prevent replacement of the last invoke in the assembly with proxy, you can set the API property api.properties.x-ibm-gateway-optimize-invoke to false. For more information, see API properties.

The following table describes the properties of the invoke policy.

Table 1. Invoke policy properties
Property	Required	Description	Data type
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: Keep GET POST PUT DELETE PATCH HEAD OPTIONS The default value is `GET`. However, if set to `Keep`, or 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 gzip 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
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.	Boolean

Example

- invoke:
  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