The FX Integration API

The FX Integration API is a back-end Java library that you can use to quickly and easily integrate the Caplin FX Professional Motif with your existing systems. The library consists of a set of APIs specifically designed to provide the data expected by the Motif, in the exact format required. The FX Integration API fully supports the core features of the FX Professional Motif, including (but not limited to):

Streaming FX rates
ESP (Executable Streaming Price) trading
RFS (Request For Stream) trading
FX Orders

Contents:

Messages and fields
Standard architecture for Integrating external systems
Using the FX Integration API to integrate the Motif
Benefits of the FX Integration API

Messages and fields

When using the FX Professional Motif back-end system - Caplin Platform - to integrate with your existing back-end systems and stream real-time data to your client applications via the internet, the server-side APIs that you interact with are generally based on receiving requests and sending messages made up of fields. These fields are simple key/value pairs. The FX Integration API enforces a contract with the Motif; this enables developers to implement DataSource Integration Adapters conforming to the pricing and trading workflow that the Motif expects, without being overly concerned with field and message specifications.

Thus the FX Integration API enables you to fully utilise all of the Motif features while greatly reducing the amount of time developing integration adapters by writing a small amount of high level domain-specific integration code rather than writing a lot of low-level boilerplate code to build up raw messages and manually set fields.

See the following sections on how this is achieved.

Standard architecture for Integrating external systems

As the FX Professional Motif back-end technology is powered by Caplin Platform 6, it allows you to integrate with any back-end system and stream real-time data to your client applications over the internet using Liberator.

This diagram shows how you would typically use the Caplin Platform architecture to integrate with an external Pricing System and Trading System to send data to a front end/ client application.

Two DataSource Integration Adapters are illustrated in the diagram above; one for sending streaming prices to the client application and one to handle trading.

For each coloured layer:

Blue layers represent Caplin libraries and components.
Grey layers represent code that you would write as a developer working on the integration.
Yellow layers represent third-party libraries and components.

For the Pricing Integration Adapter

It has a simple three-layer structure.

The top layer represents the DataSource for Java library. This library allows you to listen to requests that have been sent from a client application across the internet to your Adapter via Liberator. For this Adapter, a request could be for streaming FX rates on a particular currency pair and tenor.
The middle layer consists of your own custom code, which would be responsible for transforming the request into a format that your Pricing System can understand, and then passing it to the bottom layer.
The bottom layer represents whichever library or custom code is required to communicate with the Pricing System. As an example, if your Pricing System is a FIX engine then the bottom layer might be a library such as QuickFIX/J.

When the Pricing System responds to the request, the flow is simply reversed. The bottom layer will call into your custom code with a price update for the requested currency pair and tenor. Your custom code is then responsible for transforming the update into an equivalent message that it can pass into DataSource for Java. The DataSource for Java library will then send the message to the Liberator, which will then distribute it to all of the subscribed client applications across the internet.

For the Trading Integration Adapter

This Adapter is very similar, except that it makes use of one of the higher level helper APIs which sits on top of DataSource for Java. In this case it uses the Trading Integration API, which takes care of some of the lower level message parsing and also allows you to define a state model for each type of trade using XML; where the model will be enforced by the library.

When one of the client applications sends a trade message to the Adapter it will be received by DataSource for Java as normal, parsed into a trade event by the Trading Integration API, and then passed to your custom code in the middle layer.
Your custom code is responsible for transforming the trade event into a form that can be understood by your Trading System and then submitting it.
When your Trading System responds with a confirmation or rejection, your custom code must build a suitable trade event and pass it into the Trading Integration API, so that it can be turned into a DataSource for Java message and sent back to the client application via Liberator.

In this example although your custom code in the Trading Integration Adapter is only interacting with the Trading Integration API, it still has access to the underlying DataSource for Java instance. So you are free to send non-trade related messaging directly through DataSource for Java from your custom code in addition to handling trades, if you wish to do so.

Using the FX Integration API to integrate the Motif

Supplied with the FX Integration API is an Adapter Suite containing the source code for a number of example Integration Adapters, which demonstrate best practices for how to use the API.

NovoRatesAdapter: shows how to send streaming executable FX rates to the FX Professional Motif, for use in the quick-trade tiles.
NovoTradingAdapter: shows how to handle the two most common trade types, ESP and RFS.
NovoOrderAdapter: shows how to deal with single orders and multi-order strategies.
NovoCalendarAdapter: shows how to send tenor dates (also called value dates) and valid settlement dates to the Motif.
NovoPermissioningAdapter: shows how to send all of the permissions required by the Motif into Liberator.

These example Adapters implement two notional business names by convention. Novo is short for Novo Bank, and represents a bank that wants to provide an online trading facility to their customers using the FX Professional Motif. Typically, the developers at Novo Bank would be responsible for writing the Integration Adapters using the FX Integration API, in order to link the bank’s systems with the Motif.

The other name we use in the example Adapters is BTS, which stands for Best Trading System. This represents a trading system or OMS used by the bank, for example Refinitiv Electronic Trading. The BTS code provided is intended to provide just enough canned data and mock behaviour to make the Motif work. For example, it will generate canned FX rates and will confirm trades. This allows most of the functionality in the Motif to work when running against the Novo Adapters, such as streaming rates and basic trading.

The example Adapters consist of a thin layer of code between the BTS system and the FX Integration API. When you look at the example adapters, you should treat the BTS code as a black box and concentrate on the Novo code in the middle layer, because this is the code you would typically write as a developer working on the Motif integration.

By starting with the FX Integration API you gain a number of advantages over developing a DataSource Integration Adapter using the generic DataSource for Java library. You also lose none of the freedom to augment the messaging with your own custom fields or send your own streaming data; which is completely custom to your application.

Architecturally, you can think of the FX Integration API as a higher level helper library that sits on top of DataSource for Java and its own helper libraries. The FX Integration API is specifically tailored to serving the FX Professional Motif. It alters the structure of your Integration Adapters by adding an extra layer, see diagram below:

You can now see how the Integration Adapters communicate primarily with the FX Integration API. Since the FX Integration API takes care of much of the low level message parsing code, the amount of custom code you need to write in the middle layer is significantly reduced.

You will notice from the above diagram that the underlying DataSource for Java instance used by the FX Integration API is still exposed and available to your custom code to call into directly. This means that the FX Integration API does not prevent you sending any custom messages you like to the front end. As a general rule you should use the FX Integration API if you want to provide functionality supported in the FX Professional Motif, such as streaming rates, ESP and RFS trades. Although, you are free to bypass the FX Integration API when you wish to implement your own, new features which are not supported out of the box.

Once you have followed the Deploying the FX Professional Motif guide and set up all of the systems, you can begin customising the Novo Adapters, or simply use them as a reference to build your own Integration Adapters from scratch.

Benefits of the FX Integration API

Here are the main benefits to using the FX Integration API to integrate with the FX Professional Motif rather than the lower level message passing APIs like DataSource for Java:

Writing less code

Writing a DataSource Integration Adapter involves writing some low level code to handle things like building and sending messages, or providing the latest data from a cache if you receive a request from a new peer. We have identified the common boilerplate code that is written when creating adapters to integrate with various external systems, and moved it into the FX Integration API. This all means your custom code becomes smaller, faster to write, and easier to test.

Compatibility with the Motif

As the FX Professional Motif has a contract with the FX Integration API rather than a single set of custom integration adapters, any back-end systems that integrate with the FX Integration API are guaranteed to work with the Motif. This then allows us to build a library of pre-built, reusable Motif front-end blades and components from which you can pick and choose to conveniently slot into your web trading application.

Freedom to extend, customise and bypass the FX Integration API

Although the FX Integration API is specifically built to meet the exact requirements of the FX Professional Motif, it is fully extensible and customisable. As an example, if you wish to customise the Motif to send some extra fields on an ESP trade, you will find that the object representing an ESP Submit event allows you to read fields by name in addition to calling the built-in getter methods.

The Motif provides support for the most common order strategies, such as OCO (One Cancels the Other) and If-Done. However if you wish to customise this behaviour you can plug in your own class to parse incoming trade events into strategy objects, rather than using the parser provided. You can even plug in your own classes to support completely custom order strategies that you devise, instead of (or as well as) customising the built-in strategies.

Developers are provided with the ability to side-step the default behaviour of the Motif - at no point should the FX Integration API lock you into doing anything a certain way. You are free to bypass the FX Integration API altogether and send your own custom messages, as the underlying DataSource for Java instance used by the FX Integration API is freely accessible and not hidden.