Overview 

This document contains a description of REST Initiator Transport Adaptor for FixEdge and common steps required to configure and use it. 

FIXEdge REST initiator adaptor is a module in FIXEdge which sends FIX message from Business Layer to destination system as an http(s) REST POST request. 

The adapter has the following features:

• Send Raw FIX message
• Send FIX message in JSON format
• Send XmlData (213) tag data
• Secure connection support
• Proxy server support
• Message validation

Outgoing message representations 

An outgoing HTTP message body can be formed in several modes:

• Raw FIX message with SOH as a delimiter
• JSON representation of FIX messages tags and values
• content of tag XmlData (213) of the FIX message

The message conversion type is specified with TransportLayer.RestOutTA.ConversionMethod parameter.

Raw FIX message

Example of raw FIX message (pipe symbol stands for SOH symbol): 

8=FIX.4.2|9=153|35=D|49=BLP|56=SCHB|34=1|50=30737|97=Y|52=20000809-20:20:50|11=90001008|1=10030003|21=2|55=TESTA|54=1|38=4000|40=2|59=0|44=30|47=I|60=20000809-18:20:32|10=061| 

JSON

Example of JSON message (contains repeating groups): 

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

Session level tags: BeginString(8), BodyLength(9), SenderCompID(49), TargetCompID(56) and CheckSum(10) are not inserted in output JSON body. 

Body of XmlData (213) tag

Tags XmlData (213) and XmlDataLen (212) can present in any message type. One of the common ways to use it is to create an XML message (e.g. non-FIX MsgType) (n) as FIX message wrapper over non-FIX message. The Rest Adapter can extract the data from the XmlData (213) and send it to the external services.

The example of exporting data from tag XmlData (213) (FIX message 35=n contain another FIX message 35=AE (marked orange) within XmlData (213) ):

Using security and non-secure connections 

The Transport Adapter supports secure (https) and non-secure (http) connections, for details see. 

Message validation 

Message validation is configured by using TransportLayer.RestOutTA.ValidateFIXMessage. 

Example1: validation is off: 

TransportLayer.RestOutTA.ValidateFIXMessage = No 

Example2:  a message is not sent, OnUndelieveredEvent on BL is generated: 

TransportLayer.RestOutTA.ValidateFIXMessage = ValidateAndReject 

Example of log record:

2020-02-12 12:18:11,971 UTC   WARN    [RestInitiatorClient2]  140246545049344  FIX validation error: Incorrect integer value in tag 67: 'check'[Group tag=73, Entry #=0] in message New Order - List (E) with sequence number 3.2020-02-12 12:18:11,971 UTC   ERROR   [RestInitiatorClient2]  140246545049344  Error in sendToClient: Incorrect integer value in tag 67: 'check'[Group tag=73, Entry #=0] in message New Order - List (E) with sequence number 3.

For details see. 

Error handling 

Error information about HTTP error codes is saved to log, see logging section. 

A user can handle errors with Business Layer Engine in case of  error responses from the destination system (for example receiving 400 or 500 error codes).   

An OnUndeliveredMessageEvent is generated and an undelivered message is transferred to FIXEdge Business Layer for further processing. In the example below rejected message from RestInitiatorClient will be sent to FIX session : 

<OnUndeliveredMessageEvent> 
    <Source> 
        <Client Name="RestInitiatorClient"/> 
     </Source> 
   <Action> 
        <Send><FixSession SenderCompID="FE" TargetCompID="SC"/></Send> 
    </Action> 
</OnUndeliveredMessageEvent> 

Logging 

The transport adapter uses category RestOutTA for logging REST events.

The category of the other actions can be defined by the user in order to track Transport Adapters events from different adapters.

The list of logged actions:

• Adapter initialization
• Parsing information, validation errors
• Configuration parameters
• sent and received messages

Additional information about logging configuration can be found there: 

• FIXEdge logs format
• How to redirect FIX Antenna and/or FIXEdge logging to Syslog instead of files
• How to divide different categories and severities of log files into different files in the Logging section

Configuration example #1 (Enable extra logging levels)

The following configuration example shows how to enable Note, Debug and Trace level of REST events; specifies logging category for RestOutTA1 as RestInitiatorClient1 and enable Note, Debug and Trace level of RestOutTA1 adapter.

TransportLayer.RestOutTA1.LogCategory = RestInitiatorClient1 
Log.RestOutTA.Device = File 
Log.RestOutTA.DebugIsOn = true 
Log.RestOutTA.TraceIsOn = true 
Log.RestOutTA.NoteIsOn = true 
Log.RestInitiatorClient1.Device = File 
Log.RestInitiatorClient1.DebugIsOn = true 
Log.RestInitiatorClient1.TraceIsOn = true 
Log.RestInitiatorClient1.NoteIsOn = true

FIXEdge log example for this configuration: 

2019-10-29 13:34:04,676 UTC   INFO    [RestOutTA]  10012  Log Category is registered to FileLogger 
    Category name: RestOutTA 
    File name: '../FIXEdge1/log/FixEdge.log' 
    File record format: %date{ISO8601} %timezone   %level%tablevel   [%logger]  %thread  %message 
    Create unique file name: off 
    Recreate file on restart: off 
    Flush on each record: on 
    Time zone: UTC 
    Log rotate is on: 
        size limit is 104857600 
        File Limit: 10 
        Rotate directory: ../FIXEdge1/log 
    Note: Filename is shared with other categories 
2019-10-29 13:34:04,677 UTC   DEBUG   [RestInitiatorClient1]  10012  Setting up HTTP session with jsonplaceholder.typicode.com:80 endpoint 
2019-10-29 13:34:04,677 UTC   DEBUG   [RestInitiatorClient1]  10012  Timeout for client 'RestInitiatorClient1' = 60. 
2019-10-29 13:34:04,677 UTC   INFO    [CC_Layer]  10012  Client RestInitiatorClient1 has logged in 
2019-10-29 13:34:04,677 UTC   INFO    [RestInitiatorClient1]  10012  REST Initiator TA v.0.0.0.1 started. 
2019-10-29 13:34:04,677 UTC   INFO    [TransportLayer]  10012  Module 'TransportLayer' version 0.1.1.5 was loaded. 
2019-10-29 13:34:04,677 UTC   INFO    [CC_Layer]  10012  Admin REST API is disabled 
2019-10-29 13:34:04,677 UTC   INFO    [CC_Layer]  10012  Control Centre XML Sockets Monitor is started 
2019-10-29 13:34:04,677 UTC   INFO    [CC_Layer]  10012  Control Centre Layer is initialized 
2019-10-29 13:34:04,677 UTC   INFO    [CC_Layer]  10012  FixEdge pid file '../FIXEdge1/log/FixEdge.pid'. 
2019-10-29 13:34:04,678 UTC   INFO    [XmlSockImpl]  12532  Log Category is registered to FileLogger 

Configuration example #2 (Log to separate file)

The following configuration example shows how to log Transport Adapter events into a separate log file FIXEdge1/log/RestOutTA.log: 

TransportLayer.RestOutTA1.LogCategory = RestInitiatorClient1 
Log.RestOutTA.Device = File  
Log.RestOutTA.DebugIsOn = true 
Log.RestOutTA.TraceIsOn = true 
Log.RestOutTA.NoteIsOn = true 
Log.RestOutTA.File.Name = FIXEdge1/log/RestOutTA.log 
Log.RestInitiatorClient1.Device = File 
Log.RestInitiatorClient1.DebugIsOn = true 
Log.RestInitiatorClient1.TraceIsOn = true 
Log.RestInitiatorClient1.NoteIsOn = true 
Log.RestInitiatorClient1.File.Name = FIXEdge1/log/RestOutTA.log 

RestOutTA.log example

2019-10-29 13:40:07,830 UTC   INFO    [RestInitiatorClient1]  18488  Log Category is registered to FileLogger 
    Category name: RestInitiatorClient1 
    File name: '../FIXEdge1/log/RestOutTA.log' 
    File record format: %date{ISO8601} %timezone   %level%tablevel   [%logger]  %thread  %message 
    Create unique file name: off 
    Recreate file on restart: off 
    Flush on each record: on 
    Time zone: UTC 
    Log rotate is on: 
        size limit is 104857600 
        File Limit: 10 
        Rotate directory: ../FIXEdge1/log 
2019-10-29 13:40:07,830 UTC   DEBUG   [RestInitiatorClient1]  18488  Setting up HTTP session with jsonplaceholder.typicode.com:80 endpoint 
2019-10-29 13:40:07,830 UTC   DEBUG   [RestInitiatorClient1]  18488  Timeout for client 'RestInitiatorClient1' = 60. 
2019-10-29 13:40:07,831 UTC   INFO    [RestInitiatorClient1]  18488  REST Initiator TA v.0.0.0.1 started. 

Configuration  

See How to configure adapters in FIXEdge for a guide on how to enable Transport Adapter functionality in FIXEdge.

Using proxy server feature

Transport Adapter supports proxy server configuration for cases when a direct connection from the FIXEdge server to the destination system is forbidden. 

A host, port, user and password for proxy connection should be configured in FIXEdge.properties file, for details, see. 

Configuration example 

A typical configuration for windows

TransportLayer.TransportAdapters = TransportLayer.RestOutTA1
TransportLayer.RestOutTA1.Description = RESTInitiatorClient1 
TransportLayer.RestOutTA1.DllName = bin/REST_Initiator_TA-vc10-MD-x64.dll 
TransportLayer.RestOutTA1.Type = DLL 
TransportLayer.RestOutTA1.ClientID = RestInitiatorClient1 
TransportLayer.RestOutTA1.LogCategory = RestInitiatorClient1 
TransportLayer.RestOutTA1.Protocol = HTTP 
TransportLayer.RestOutTA1.ServerHost = jsonplaceholder.typicode.com 
TransportLayer.RestOutTA1.ServerPort = 80 
#TransportLayer.RestOutTA1.ProxyHost = 
#TransportLayer.RestOutTA1.ProxyPort = 
#TransportLayer.RestOutTA1.ProxyLogin = 
#TransportLayer.RestOutTA1.ProxyPassword = 
TransportLayer.RestOutTA1.URI = /posts 
TransportLayer.RestOutTA1.SendingTimeout = 60 
TransportLayer.RestOutTA1.SendingMaxAttempts = 2 
TransportLayer.RestOutTA1.ConversionMethod = NumericTagValueMapping 
TransportLayer.RestOutTA1.ValidateFIXMessage = ValidateAndWarn 
Log.RestOutTA.Device = File Console    
Log.RestOutTA.DebugIsOn = true 
Log.RestOutTA.TraceIsOn = true 
Log.RestOutTA.NoteIsOn = true 
Log.RestOutTA.File.Name = FIXEdge1/log/RestOutTA.log 
Log.RestInitiatorClient1.Device = File 
Log.RestInitiatorClient1.DebugIsOn = true 
Log.RestInitiatorClient1.TraceIsOn = true 
Log.RestInitiatorClient1.NoteIsOn = true 
Log.RestInitiatorClient1.File.Name = FIXEdge1/log/RestOutTA.log 

Example of a configuration block with security parameters: 

TransportLayer.RestOutTA1.Protocol = HTTPS 
TransportLayer.RestOutTA1.HTTPS.PrivateKey = FIXEdge1/conf/TestRESTAPI.key 
TransportLayer.RestOutTA1.HTTPS.Certificate = FIXEdge1/conf/TestRESTAPI.crt 
TransportLayer.RestOutTA1.authHeader = apikey 
TransportLayer.RestOutTA1.authValue = QWERTY0123456789

Monitoring Rest Initiator Transport Adapter with FIXICC

REST Initiator Transport Adapter is displayed in FIXICC in the tree in the "servers" list at the left. In the example below RestOutTA1 is an adapter name and ResInitiatorClient1 is ClientID. Messages statistics is shown at the right -

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

On the picture below the configuration with two Rest Initiator adapters is shown (RestOutTA1 and RestOutTA2).

Routing 

The Transport Adapter can be accessed in BL via ClientIDparameter. See the example of BL_Config.xml rule below (ClientID=RestInitiatorClient1): 

<Rule> 
          <Source> 
               <FixSession SenderCompID="FIXCLIENT1" TargetCompID="FIXEDGE"/> 
          </Source> 
               <Action> 
                    <Send Name="RestInitiatorClient1" /> 
               </Action> 
</Rule> 

Troubleshooting 

In all trouble cases first of all check error information in REST TA logfile (defined by Log.*.File.Name parameter) and FIXEdge.log.  

To check the Adapter is started correctly search for the string "REST Initiator", the example of output: 

REST Initiator TA v.0.0.0.1 started 

Host not found 

Description 

Message is not sent, adapter is initiated correctly, user gets error in REST TA log file: 

In FIXEdge.log: 

Solution 

Possible reason is the wrong host. Check the host is available (ping  <ServerHost> ). If the host is available contact Support, otherwise correct TransportLayer.RestOutTA.ServerHostparameter value in adapter configuration. 

Send to Client failed 

Description 

Message is not sent, adapter is initiated correctly, user gets error in REST TA log file: 

Solution 

A possible reason is wrong URI. If the URI value is correct contact Support, otherwise correct the TransportLayer.RestOutTA.URIparameter value in adapter configuration. 

Validation error 

Description 

User gets validation error, but message is sent successfully: 

User gets validation error, message is rejected: 

Solution 

Validation error means that FIX message has incorect tag values of message structure. In the first case message is sent successfully because ValidateFIXMessage = ValidateAndWarn is set up. In the second case message is rejected because ValidateFIXMessage = ValidateAndReject is set up. Possible actions: 

• correct message 
• update dictionary 
• turn off validation: TransportLayer.RestOutTA.ValidateFIXMessage = No). 

Wrong security options 

Description 

Message is not sent, adapter is initiated correctly, user gets error in log: 

or: 

Solution 

A possible reason is security parameters are not correct - do not correspond to destination system connection properties. Try to change  TransportLayer.RestOutTA.Protocol or TransportLayer.RestOutTA.ServerPort parameters.