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. 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 is 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 or an OpenAPI 3.0 document and configure a RESTAsyncRequest node by completing the following steps:

  1. Create a message flow to include your RESTAsyncRequest node.
    For more information about creating a message flow, see Creating a message flow.
  2. Optional: If you intend to Configure the REST request node manually at step 3, you must populate the REST APIs Catalog.

    Each project in the Application Development view has a REST APIs Catalog folder that contains a list of all the REST APIs that are available in the project for use with RESTRequest and RESTAsyncRequest nodes. Each REST API folder in the REST APIs Catalog contains a list of all the available operations in the REST API. Populate the REST APIs Catalog by completing the following steps:

    1. Right-click a project or an application in the Application Development view and select Import. Alternatively, select File > Import.
    2. Select RESTAPIs > RestAPI definition to open the Import a RESTAPI definition dialog.
    3. Select a project from the Project menu or click New to create a new project.
    4. Select Select an OpenAPI document from the workspace or from a file system or Retrieve an OpenAPI document from a URL using HTTP or HTTPS.
    5. Click Next to open the Import a RESTAPI definition dialog.
    6. Depending on the choice you made at substep d, you are prompted to select a file from a file system or a project in the workspace, or specify a URL.
    7. Click Next to review the details of the RESTAPI that you want to import.
    8. If the details of the RESTAPI are correct, click Next
    The Swagger document or OpenAPI 3.0 document is copied into the REST APIs Catalog and the Other resources folder for the project that contains the RESTRequest node, and is visible in the Application Development view.
  3. Drag a RESTAsyncRequest node from the palette onto the message flow canvas, and configure it to use an imported Swagger document or an imported OpenAPI 3.0 document that contains the operation that you want to invoke.
    Alternatively, you can drag 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 or the imported OpenAPI 3.0 document, and specify parameter values as node properties, by 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 or OpenAPI 3.0 document that contains the operation that you want to use:
      • Select a Swagger document or an OpenAPI 3.0 document from a referenced project or from a file system

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

        If you want to use a Swagger document or an OpenAPI 3.0 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 or an OpenAPI 3.0 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 or an OpenAPI 3.0 document. This Swagger document or OpenAPI 3.0 document is downloaded and stored in the project that contains the RESTAsyncRequest node.

      • Configure the REST request node manually

        Select this option to close the wizard without changing the RESTAsyncRequest node. You can then optionally drag 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 or an OpenAPI 3.0 document from a referenced project or from a file system or Retrieve a Swagger document or an OpenAPI 3.0 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.
  4. Configure the remaining properties of your RESTAsyncRequest node.
    For more information, see RESTAsyncRequest node.
  5. 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.
  6. Configure the security credentials for interacting with the REST API, by using the mqsicredentials command command. Alternatively, you can use the mqsisetdbparms command.
    For more information, see Configuring security credentials for connecting to a REST API.
  7. 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.