Adding an invoke assembly action to retrieve documents

The invoke assembly action retrieves a document from a specified target URL from within the assembly.

About this task

For a PUT or POST request, the invoke action retrieves the headers and payload from the API context and sends the retrieved data to the target URL. For a GET request, the headers are retrieved from the API context, but no payload is sent.

Important: For an invoke assembly action to include sensitive headers from API key security definitions, you must define a set variable assembly action that adds the wanted sensitive headers to the request.headers context. The set variable action must be before the invoke action. For more information, see Adding a set variable assembly action.

After the invoke action receives the response, it stores the response in the variable that is specified by the Output property. The variable must be a writable variable in the API context. By default, the response is stored in the message variable. When an assembly contains multiple invoke actions, you can store the output of each invoke action in a different variable.

The invoke action can deliver and accept multipart messages (requests and responses). Multipart messages are set to Content-Type: multipart/related. The following excerpt shows an example of a multipart request. The root part and attachments are separated by boundaries. The root part contains a JSON document and the two attachments contain the base64-encoded text and document.

POST /mime-test/v1/base HTTP/1.1
Host: localhost:2059
Content-Type: multipart/related; type="application/json"; boundary="----=_boundary"
Content-Length: 417

------=_boundary
Content-Type: application/json
Content-ID: start

{ "message": "hello" }
------=_boundary
Content-Type: text/plain
Content-Id: <secret>
Content-Transfer-Encoding: BASE64

c2VjcmV0IHRleHQgMTIzCg==
------=_boundary
Content-Type: text/xml; charset=utf-8
Content-Id: <data>

<msg>Hello</msg>
------=_boundary--

The processing for a multipart message is as follows.

The assembly includes a parse action.

Attachments in the request or response can be manipulated and sent back to the client.
By default, the response is sent to the client in multipart format. Alternatively, you can clear context.message.attachments to discard the attachments and send only message.body to the client. For more information, see context object for the API gateway.

The assembly does not include a parse action.

For a multipart request where the message.body variable is not changed, the invoke action keeps and passes the attachments to the server.
For a multipart request or response where the message.body variable is not changed, the result API action passes the attachments as the final response.
If the message.body variable is changed, attachments are discarded.

You can specify the message type of the payload to send to the target server or specify to detect the message type.

When binary, indicates to package the payload as binary and send, regardless of the message type.
When detect, indicates to detect the message type and send based on detected type. By default, the message type is detected.
When GraphQL, indicates to package as GraphQL and send. If the message type is not GraphQL, the action fails.
When JSON, indicates to package as JSON and send. If the message type is not JSON, the action fails.
When XML, indicates to package as XML and send. If the message type is not XML, the action fails.

You can specify the type of payload to send for GraphQL POST requests. When set to GraphQL or JSON, this setting overrides the message type of the payload.

Detect: Indicates to detect the message type and send based on detected type. By default, the message type is detected.
GraphQL: Indicates to send GraphQL.
JSON: Indicates to send JSON.

You can specify the following settings.

You can set whether to enable the Stop on error property.
- When enabled, specify which error conditions stop processing. The following choices are available.
  
  Connection error
  
  The action cannot establish a connection to the target URL. For example, the host is not reachable or the service is not available.
  
  SOAP error
  
  The action receives a 500 SOAP fault as response.
  
  Operation error
  
  The action establishes the connection and receives a non-2xx response.
When one of the selected error conditions occur, the following activities occur.
- An error is triggered. A sample error message is as follows.
```
{
  name: 'ConnectionError',
  message: 'Invalid URL'
}
```
- The error data is written to the error.variable variable, where the error.name variable is set to ConnectionError, SOAPError, or OperationError.
- Assembly processing stops.
When enabled but error conditions are not specified or when not enabled, the action completes and continues to process the next action in the assembly. In these situations, the error data is written to the output.status.condition variable. For illustrative purposes, foo is the output variable.

ConnectionError

foo.status.connectionError

SOAPError

foo.status.soapError

OperationError

foo.status.operationError
Whether to attempt to resolve redirects. Some protocols generate redirects as part of the protocol; for example, HTTP response code 302. By default, does not resolve redirects.
Whether to restrict transactions to HTTP/1.0. The property is deprecated. You must specify the HTTP protocol version.
The HTTP protocol version for the connection. When HTTP/2, whether the connection must use HTTP/2.
When the protocol version is HTTP/1.1, the connection can request a WebSocket upgrade. The Allow WebSocket upgrade (deprecated) property in this action is deprecated. Instead, define a WebSocket upgrade assembly action and assign it to the assembly. For more information, see Adding a WebSocket upgrade assembly action.
Whether to send documents to the server with Transfer-Encoding: chunked. When the service uses HTTP/1.1, the body of the document can be delimited by either Content-Length or Transfer-Encoding: chunked. While all servers can interpret Content-Length, many applications fail to understand Transfer-Encoding: chunked. For this reason, Content-Length is the standard method.
The use of Content-Length interferes with the ability of the service to fully stream. If you must stream full documents to the target server, set this property to on.

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.
Whether to enable HTTP persistent connections.
With the cache type, you can set whether and how to cache documents in the response.
No cache

Does not cache any documents.

Protocol

Uses the cache behavior that is defined by the Cache-Control headers on the request and response. When used, the invoke action forwards the Cache-Control header from the client to the target and sends the Cache-Control header from the target back to the client.
To optimize performance, the API gateway sends only one request to the target URL when it receives multiple requests for a resource that is not in the cache but is cacheable. The remaining requests are not processed until the response from the first request is received and the cache behavior is determined.
- When the response indicates that caching is possible, the gateway responds to all waiting requests with the cached resource.
- When the response indicates that caching is not possible, the gateway sends all waiting requests to the target URL.
You can specify a cache key, which is the unique identifier, for the document cache entry. By default, the URL is the cache key.

Time to live
Keeps documents in the cache for a specified time.
- You must specify the validity period for documents in the cache.
- You can control whether to cache responses to POST and PUT requests. By default, responses to POST and PUT requests are not cached.
- You can specify a cache key, which is the unique identifier, for the document cache entry. By default, the URL is the cache key.
Whether to decode request parameters that are referenced in the target URL.
Whether to encode the + character in a request parameter that is referenced in the target URL.
Whether to include the payload for a DELETE request.
Whether to inject the default User-Agent header to the API request when it is not found in the incoming request. By default, this header is injected when not found in the incoming request.
Whether to inject proxy headers to the API request. The proxy headers are X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Port, and X-Forwarded-Proto. By default, these headers are not injected.
The control list to manage whether headers are accepted or rejected. By default, all headers are accepted.
The control list to manage whether URL parameters are accepted or rejected. By default, all URL parameters are rejected.
The correlation path indicates the part of the API definition that correlates with the assembly action. This path is included in the debug data for use by debugging tools. For example, when an API configuration is specified in an OpenAPI document with gateway extensions, this path is the JSON path to the policy in the IBM extensions section of the document. The path can be expressed in any form that the debugging tool can correlate to the API definition.

Procedure

In the search field, enter invoke.
From the search results, click Invoke assembly action.
Click Add.
Define the basic properties: Name, administrative state, descriptive summary, title, and correlation path.
Specify the URL to use.
Optional: Specify the TLS client profile to secure the connection to the target URL.
Optional: Specify the time to wait before the reply is received from the target.
Optional: Specify the username and password alias for HTTP basic authentication.
Specify the HTTP method to use for the invocation.
When you set to Keep, the HTTP method from the incoming request is used.
Specify the message type of the payload.
When the message type of the payload is set to GraphQL or Detect, specify the type of payload to send for GraphQL POST or KEEP requests.
Set whether to enable HTTP compression.
Define the document cache settings.
1. Set the cache type.
  This property takes effect only when a response is received from the target. When set, the invoke action always returns the nonexpired response from the cache.
2. When the cache type is Time to Live, specify the validity period for documents in the cache.
3. When the cache type is Time to Live, specify whether to cache responses to POST and PUT requests.
4. When the cache type is Time to Live or Protocol, specify a unique identifier to use as a key for the document cache entry. When omitted, the entire URL string is used as the key.
Set whether to attempt to resolve redirects.
Define the HTTP settings to connect to the server.
The ability to restrict to HTTP/1.0 is deprecated. You must set the HTTP protocol version.
1. Set the HTTP protocol version for the connection.
2. When set HTTP/2, indicate whether the connection requires HTTP/2.
Set whether to send documents to the server with Transfer-Encoding: chunked.
Set whether to enable HTTP persistent connections.
Set whether the flow stops when a particular type of error occurs during assembly processing.
When the flow is set to stop on error, specify the type of errors on which the flow stops.
Specify the name of a variable to store the invoke action output.
By default, the output is stored in the message.body, message.headers, message.status.code, and message.status.reason in the API context.
Set whether to decode request parameters.
Set whether to encode + characters.
Set whether to include the payload for a DELETE request.
If the User-Agent header is not found in the incoming request, set whether to inject the default User-Agent header to the API request.
Set whether to inject proxy headers to the API request.
Set the control list that manages whether headers are accepted or rejected.
Set the control list that manages whether URL parameters are accepted or rejected.
Click Apply to save changes to the running configuration.
Click Save to save changes to the persisted configuration.