Asynchronous API Operations

Overview

Several API operations cannot be completed within the scope of a normal HTTP request. For example, a settlement request might take more than 24 hours to reach a settled state, and sending an HTTP response within a realistic read timeout interval is not possible.

Operations that can potentially take a long time to complete need a way to send an asynchronous reply/event message to the original caller.

Advanced Message Queuing Protocol (AMQP)

Asynchronous reply/event messages that take a long time to complete are sent to queues on an externally-exposed RabbitMQ server. RabbitMQ is an open-source message broker that implements the AMQP standard. API clients using these asynchronous operations must run AMQP consumers to process reply/event messages as they become available in these queues.

Using AMQP for asynchronous reply/event messages rather than alternative approaches such as http polling or callbacks has the following advantages:

AMQP can reliably deliver messages through message acknowledgments. If an unrecoverable error occurs when processing a message and an acknowledgment is not sent, the broker redelivers the message in the future, guaranteeing at-least-once delivery.
All communication with the broker can take place over a single, client-initiated connection. No firewall configuration changes are needed at the client site, as would be the case with callbacks.
Clients connect to port 443 (the default HTTPS port), which most likely is already an open port if using a firewall. This AMQP connection is significantly less "chatty" than a polling API operation.

Webhooks as an Alternative to AMQP

If technical limitations prevent you from implementing AMQP for asynchronous messages, you can use an alternative implementation with Webhooks and HTTPS. For details on Webhooks and a comparison of the two implementations, see Webhooks Implementation for Asynchronous Messages.

Payment Service Asynchronous API Operations

The Payment Service uses the following asynchronous API operations:

Risk Service Asynchronous API Operations

The Risk Service uses the following asynchronous API operations:

Risk Assessment

Processing Flow

The asynchronous API operations follow the same basic processing flow:

The order management system requests an asynchronous API operation.
The operation completes the necessary processing.
The operation sends a reply/event message to the order management system over AMQP.
The order management system processes and/or persists the message.
The order management system sends an acknowledgment message to the message broker.

Additional Information

Example RabbitMQ Subscribers

RabbitMQ Tutorials

AMQP Basics

AMQP Specification