Page History

Table of Contents

Overview

This document contains a description of the main features of REST Transport Adaptor for FixEdge and common steps required to install the REST Transport Adaptor (REST TA) for the FIX Edge.

Concept

FIXEdge REST adaptor is a REST server that handles REST requests with incoming messages in JSON form, converts them to FIX format and sends to the target. The adapter is designed for generic processing of messages, without lock-in to the specific message type.

Depending on configuration settings, the adaptor can transform incoming message to either FIX XML message of 'n' type, or map JSON fields into FIX tags. The type of resulting message should be defined in tag 35.

JSON format of message might look like follows:

'{"35":"D", "1":"12345", "56":"CITIGROUP", ..........}'

The adaptor supports repeating groups and nested repeating groups.

Requests are sent as HTTP POST requests to following URL: http://<Address>:<ListenPort>/messages

Example of REST request using curl for localhost and listen port 8001:

curl -H "Content-Type: application/json" -X POST -d "{\"35\":\"D\",\"1\":\"USD\",\"386\":[{\"336\":\"ABCD\"}]}" http://localhost:8001/messages

Resulting FIX messages can be optionally validated against FIX dictionaries defined in the engine.properties configuration file.

As a result of REST request the adapter should return HTTP status code:

• 200 - Success
• 202 - Accepted, returned when a message is successfully received and parsed, but couldn't be delivered to the client in FE
• 400 - HTTP error Bad Request (with JSON content including error message), in case of wrong input message or validation errors
• 404 - HTTP error Not found for requests with the wrong URL  

Logging for received and send messages

FIXEdge REST adaptor can be configured to write into separate log file the following data:

• Content of input request
• Resulting FIX messages
• HTTP status returned to the caller

Integration with FIXICC

The adaptor supports monitoring of its current state with FIXICC. It provides the following monitorable properties:

• number of received messages
• number of sent messages
• number of rejected messages

Description of JSON format for input messages:

• Fields in input JSON message are listed as pairs of "FIXID":"FIXValue".

• JSON message can contain repeating groups represented as follows:

  Code Block
  { "NoRecordsID": [      { "FIXID":"FIXValue", "FIXID":"FIXValue"... },      { "FIXID":"FIXValue", "FIXID":"FIXValue"... }     ...    ] }

Message Conversion Methods

REST Acceptor TA supports two conversion methods:

1. Raw (available since FIXEdge 6.9.0)
          a. Adapter accepts any FIX message
          b. Adapter routes FIX message to BL
2. WrapInXmlMessage 
   1. Adapter accepts any JSON
   2. Adapter creates FIX message 35=n (XML Message)
   3. Adapter stores received JSON as-is in tag 213 (XmlData)
   4. Adapter routes FIX message to BL
3. NumericTagValueMapping
1. Adapter accepts JSON, structured as described in JSON format for input messages section
2. Adapter seeks tag-value pair "35":"XYZ" in incoming JSON
3. If tag-value pair "35":"XYZ" is not found, or XYZ is not a valid FIX message type, adapter returns an error.
4. The adapter creates empty FIX message with MsgType 35=XYZ 
5. For every tag-value pair in JSON corresponding tags/values are filled in FIX message by Adapter
6. Adapter routes FIX message to BL

Examples of input/output messages (pipe symbol stands for SOH symbol):

{"66":"List1",
"56":"RESTAdapter",
"34":"3",
"35":"E",
"68":"2",
"49":"JAVA",
"394":"3",
"116":"OMS1",
"50":"30737",
"52":"20150101-01:01:01.080",
"73":[{"11":"0003",
"55":"MSFT",
"67":"1",
"54":"1",
"100":"DSMD",
"38":"100"},
{"11":"0004",
"55":"IBM",
"67":"2",
"54":"2",
"100":"DSMD",
"38":"200"}]}

FIX Message validation

REST Acceptor TA can be configured to validate converted FIX messages. FIX Message validation uses default validation options:

• prohibitTagsWithoutValue = true
• verifyDataTagsSequence = true
• verifyTagsValues = true
• prohibitUnknownTags = true
• prohibitDuplicatedTags = true
• verifyReperatingGroupBounds = true
• checkRequiredGroupFields = true
• allowZeroNumInGroup = false
• ignoreUnknownFields = false 

Installation steps

 In order to setup REST TA for FIX Edge you need:

1. Copy FIXEdge distribution package to the FIX Edge home:

Unpack the content of distribution package to FIXEdge root directory, e.g. to the C:\FIXEdge.

2. Enable TA to be used by FIX Edge

In the ‘Transport Layer Section’ of the FIXEdge.properties add REST TA to the list of supported adapters:

TransportLayer.TransportAdapters = TransportLayer.RestTA

Note: if you use other transport adapters, just add TransportLayer.RestTA to the end of the list, e.g:

TransportLayer.TransportAdapters = TransportLayer.SmtpTA, TransportLayer.RestTA

3. Configure TA

3.1.   Add REST TA section to the FIXEdge.properties.

A sample set of properties is given below:

TransportLayer.TransportAdapters = TransportLayer.RestTA

TransportLayer.RestTA.Description = REST Acceptor TA
TransportLayer.RestTA.DllName = bin/rest_acceptor_ta-vc10-MD-x64.dll
TransportLayer.RestTA.Type = DLL

TransportLayer.RestTA.ClientID = RestAcceptorClient
TransportLayer.RestTA.LogCategory = RestAcceptorClient
TransportLayer.RestTA.ListenPort = 8001
TransportLayer.RestTA.FIXVersion = FIX50
TransportLayer.RestTA.ConversionMethod = NumericTagValueMapping
TransportLayer.RestTA.ValidateFIXMessage = ValidateAndWarn

Note: sample settings could be copied from RESTAcceptorTA.properties file (in the doc folder of FIXEdge distribution package) to FIXEdge.properties file.

3.2.  Optionally configure logging for received and sent messages in a separate log category:

Log.RESTTA.Device = File
Log.RESTTA.DebugIsOn = true
Log.RESTTA.TraceIsOn = true
Log.RESTTA.NoteIsOn = true
Log.RESTTA.File.Name = FIXEdge1/log/RESTTA.log

4.       Restart FIX Edge to apply the changes 

Routing Messages from REST TA

REST TA Client can be referred to the business layer (BL) by ClientID name specified in the FIXEdge.properties file. Below is an example of the BL_Config.xml.

<?xml version="1.0" encoding="UTF-8" ?>
<!-- 
    FIXEdge - the XML Configuration file
    $Revision: 1.17.2.7 $
<!DOCTYPE FIXEdge SYSTEM "BusinessLayer.dtd">
-->
<FIXEdge>
    <BusinessLayer>
        <Rule>
            <Source>
                <Client Name="RestAcceptorClient"/>
            </Source>
            <Condition>
                <MatchField Field="35" Value=" D|G|F|n " />
            </Condition>
            <Action>
                <Send>
                    <FixSession SenderCompID="FIXEDGE" TargetCompID="FIXCLIENT"/>
                </Send>
            </Action>
        </Rule>
 
        <DefaultRule>
            <Action>
                <DoNothing/>
            </Action>
        </DefaultRule>
    </BusinessLayer>
</FIXEdge>

REST TA Configuration Parameters

Configuration of REST Adaptor contains a list of adaptor properties, HTTP server properties, and log settings:

Configuration example

The example of REST Acceptor configuration with security mode turned on:

TransportLayer.RestTA.Description = RESTAcceptorTA
TransportLayer.RestTA.DllName = bin/REST_Acceptor_TA-vc10-MDD-x64.dll
TransportLayer.RestTA.Type = DLL
TransportLayer.RestTA.ClientID = RestAcceptorClient
TransportLayer.RestTA.LogCategory = RestAcceptorClient
TransportLayer.RestTA.Protocol = HTTPS
TransportLayer.RestTA.HTTPS.PrivateKey = FIXEdge1/conf/AdminRESTAPI.key
TransportLayer.RestTA.HTTPS.Certificate = FIXEdge1/conf/AdminRESTAPI.crt
TransportLayer.RestTA.ListenPort = 8001
TransportLayer.RestTA.FIXVersion = FIX44
TransportLayer.RestTA.ConversionMethod = NumericTagValueMapping
TransportLayer.RestTA.ValidateFIXMessage = ValidateAndWarn
TransportLayer.RestTA.AuthHeader = apikey
TransportLayer.RestTA.AuthValue = QWERTY0123456789
TransportLayer.RestTA.PrivateKeyPassword = PKEYPASS123