Interacting asynchronously with REST APIs by using the RESTAsyncRequest and RESTAsyncResponse nodes

You can make REST requests and receive responses asynchronously by using RESTAsyncRequest and RESTAsyncResponse nodes in your message flow.

About this task

You might want to use asynchronous request-response processing with a backend server that has a high latency. Synchronous processing can result in many outstanding requests that require large numbers of threads to make simultaneous connections to the backend server, whereas asynchronous processing allows the response to be decoupled from the request.

You can use a pair of RESTAsyncRequest and RESTAsyncResponse nodes to interact with a REST API asynchronously. The paired nodes correlate responses against the original requests by using a unique identifier, which is specified on both nodes. Only one pair of nodes in an execution group can have the same unique identifier.

The RESTAsyncRequest node sends a REST request, and then returns control to the flow without waiting for a response. This action frees the request thread to handle further requests, while the response is handled by the paired RESTAsyncResponse node on a different thread and in a new transaction. This asynchronous functionality enables multiple outbound requests to be made almost in parallel because the outbound request is not blocked waiting for the response. The RESTAsyncResponse node can be in either the same flow or a separate flow, but it must be in the same integration server as its paired request node.

You can specify a timeout interval, so that if the whole request-response operation takes longer than the specified duration, the request is propagated to the Failure terminal on one of the paired nodes. The timeout interval applies to the interval that starts with the request being sent by the RESTAsyncRequest node, and ends with the response being completely received by the RESTAsyncResponse node.

For each request that the RESTAsyncRequest node processes, it uses a connection to send the request, and passes the connection to the paired RESTAsyncResponse node for the response. If the timeout interval is specified, the socket is closed if the interval expires. This closure ensures that a request gets only the correct response, and any response data for a request that has timed out is discarded.

The request-response processing is split between the RESTAsyncRequest node and the RESTAsyncResponse node. If a timeout occurs during the request phase of processing, the request and an exception are propagated to the Failure terminal of the RESTAsyncRequest node. Similarly, if a timeout occurs during the response phase of processing, an exception is propagated to the Failure terminal of the RESTAsyncResponse node. In most cases, the timeout would occur when waiting for a server response, in which case the Failure terminal of the RESTAsyncResponse node is used. In rare cases a timeout might occur when the request node sends data to the server. In this case, the Failure terminal of the RESTAsyncRequest node is used.

Procedure

Import a Swagger document and configure a RESTAsyncRequest node by completing the following steps:

  1. Create a message flow to include your RESTAsyncRequest node.
    For information about creating a message flow, see Creating a message flow.
  2. Drag and drop a RESTAsyncRequest node from the palette onto the message flow canvas, and configure it to use an imported Swagger document that contains the operation that you want to invoke.
    Alternatively, you can drag and drop a RESTAsyncRequest node from the palette onto a connection between two existing nodes in your message flow. The RESTAsyncRequest node is inserted into the flow between the two existing nodes.

    When you place the node onto the canvas, a wizard guides you through choosing the REST API and the operation that you want to invoke. You can select an operation from the set of operations in the imported Swagger document, and specify parameter values as node properties, using XPath or ESQL expressions to select data from the input message tree.

    1. Use the Invoke an operation in a REST API page in the wizard to specify the location of the Swagger document that contains the operation that you want to use:
      • Select a Swagger document from a referenced project or from a file system

        Select this option to display a window in which you can either specify either a location in your file system, or select a Swagger document from a referenced project. If you select a Swagger document from your file system, it is copied into the project that contains your RESTAsyncRequest node.

        If you want to use a Swagger document from a shared library that is not referenced, you must reference the shared library first, and then add the RESTAsyncRequest node.

      • Retrieve a Swagger document from a URL using HTTP or HTTPS

        Select this option to display a window in which you can specify a URL to a Swagger document. This Swagger document is downloaded and stored in the project containing the RESTAsyncRequest node.

      • Configure the REST request node manually

        Select this option to close the wizard without making any changes to the RESTAsyncRequest node. You can then optionally drag and drop an operation from the REST APIs Catalog in the Navigation onto the RESTAsyncRequest node in the message flow, and it is configured automatically to use that operation.

    2. If you selected either Select a Swagger document from a referenced project or from a file system or Retrieve a Swagger document from a URL using HTTP or HTTPS in the previous step, a window is displayed in which you can select an operation to invoke in the REST API. Select the required operation and click Finish. The RESTAsyncRequest node is automatically configured to use the selected operation.
  3. Configure the remaining properties of your RESTAsyncRequest node.
    For more information, see RESTAsyncRequest node.
  4. Add a RESTAsyncResponse node to handle the response to your REST request. This node can be in either the same flow or a separate flow, but it must be in the same integration server.
    For more information, see RESTAsyncResponse node.
  5. Configure the security credentials for interacting with the REST API, by using the mqsisetdbparms command command.
    For more information, see Configuring security credentials for connecting to a REST API.
  6. You can share data between the flow containing the RESTAsyncRequest node and the flow containing the RESTAsyncResponse node, by storing and retrieving data in the UserContext folder in the Local Environment. You can store data in the request flow under OutputLocalEnvironment.Destination.REST.Request.UserContext and you can retrieve data in the response flow from LocalEnvironment.REST.Response.UserContext. For examples, see Using local environment variables with REST nodes.