Overview 

This document contains a description of FIXEdge's REST Initiator Transport Adaptor and common steps required to configure and use it. 

FIXEdge REST initiator adaptor is a module in FIXEdge which sends FIX messages from the Business Layer to the 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

If the JSON representation is used, the "Content-Type" header in the HTTP request is set to "application/json". For all formats other than JSON, the "Content-Type" header is specified as "text/plain".

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

Raw FIX message

Example of raw FIX message (pipe symbol stands for the 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

The tags XmlData (213) and XmlDataLen (212) can appear 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 a FIX message wrapper over a 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 secure 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 

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

Error information about  HTTP error codes is saved to the log. See logging section.

An OnUndeliveredMessageEvent is generated and an undelivered message is transferred to FIXEdge Business Layer for further processing. In the example below, a 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> 

As of the FIXEdge C++ 6.11.0 release, the REST Out Transport Adapter can provide information about the error that generated an OnUndeliveredMessageEvent. Inside this event, this information can be accessed using the JavaScript functions getErrorCode and getErrorText to obtain the error values. 

• getErrorCode will return:
  • 0 if the error happened before sending the request or receiving a response from a REST server
  • an HTTP response code (for example, 500 for an internal service error)
• getErrorText will provide more information about the error in string format

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.

List of logged actions:

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

Additional information about logging configuration can be found here: 

• 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

The 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 a tree in the "servers" list at the left. In the example below, RestOutTA1 is an adapter name and ResInitiatorClient1 is a ClientID. Messages statistics are 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 troubleshooting cases, first check error information in the REST TA logfile (defined by Log.*.File.Name parameter) and the FIXEdge.log.  

To check that the Adapter has started correctly, search for the string "REST Initiator". An example of the 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 

A possible reason for this error is the wrong host. Check that the host is available (ping  <ServerHost> ). If the host is available, contact Support. Otherwise, correct the 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 

This validation error means that the FIX message has incorrect tag values for message structure. In the first case, the message is sent successfully because ValidateFIXMessage = ValidateAndWarn is set up. In the second case, the 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 for this error is that the security parameters are not correct or do not correspond to destination system connection properties. Try to change  TransportLayer.RestOutTA.Protocol or TransportLayer.RestOutTA.ServerPort parameters.