Messaging Pattern
Last updated
Last updated
The fundamental core of the Connect API is built on asynchronous messaging, which now offers options for parallel processing and various strategies to enhance your integration. You can think of the client message container as an inbox. The client initiates by sending a request to the server and then periodically checks the inbox for a response. If there are any messages in the inbox, the default behaviour is to return the oldest unread message.
The lifecycle of a single message encompasses three stages:
Sending the request
Retrieving the response
Deleting the response.
This is illustrated below:
A typical flow of API requests for payment
and account-statement
messages respectively:
Idempotency keys are an optional feature that allow you to ensure that your message request is processed at most once. This means you will not risk Connect acting on your message request twice if you retry an HTTP request due to a network interruption. Any such duplicate will be harmlessly rejected.
Idempotency keys are an X-Idempotency-Key
header that you add to your HTTP request. If present, the header value must be a UUID, generated uniquely for each unique message request. For example
The above example was generated by UUID.randomUUID()
in Java (from java.util.UUID
). Similar functions can be found in virtually any programming language, often as part of the standard library. No particular version of UUID is required - any standard form is accepted (case insensitively)
Connect will accept the first HTTP request with this idempotency key, but if another request with the same key is received, it will instead reject the message with an HTTP 409 (CONFLICT) status. This is an error code, and does mean something has gone wrong somewhere, but it also means that a previous request did succeed, so Connect has received your message fine.
Connect is guaranteed to detect and reject duplicate idempotency keys with up to 24 hours between them. In practice, it may detect those even further apart, but this should not be relied upon.
Idempotency keys should never be reused, even days apart, even for requests to different endpoints. The only reason that two HTTP requests should use the same key is if one is a retry of a failed request. For fresh requests, concerning a new message, you must generate a new UUID each time. As long as you use a standard UUID-generating function, you do not have to worry about duplicates being generated
In most cases you do not need to implement any logic by hand, as most HTTP client libraries will let you declaratively ask for retries, similar to the following pseudocode.
But for the purposes of illustration, this is the full logic that should result.
Observe that the same idempotency key may be sent multiple times. This is because all of those HTTP requests belong to one logical message request. In contrast, a new message request will get a new idempotency key.