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:
An outgoing HTTP message body can be formed in several modes:
The message conversion type is specified with the TransportLayer.RestOutTA.ConversionMethod parameter.
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| |
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.
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) ):
Input (from BL) | Output (sent to destination system) |
|---|---|
8=FIX.4.4| 9=259| 35=n| 49=0| 56=0| 34=1| 52=20200317-10:23:55.068| 212=201| 213=8=FIX.4.4| 9=168| 35=E| 49=0| 56=RESTAdapter| 34=1| 50=30737| 66=List1| 116=OMS1| 52=20191101-11:11:01.080| 394=3| 68=2| 73=2| 11=0003| 67=1| 100=DSMD| 55=11| 54=1| 38=100| 11=0004| 67=2| 100=DSMD| 55=12| 54=2| 38=200| 10=235| | 10=219| | 8=FIX.4.4| 9=168| 35=E| 49=0| 56=RESTAdapter| 34=1| 50=30737| 66=List1| 116=OMS1| 52=20191101-11:11:01.080| 394=3| 68=2| 73=2| 11=0003| 67=1| 100=DSMD| 55=11| 54=1| 38=100| 11=0004| 67=2| 100=DSMD| 55=12| 54=2| 38=200| 10=235| |
The Transport Adapter supports secure (HTTPS) and non-secure (HTTP) connections, for details see.
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 information about HTTP error codes is saved to the log. See logging section.
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).
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> |
The transport adapter uses category RestOutTA for logging REST events.
| This category cannot be re-configured |
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:
Additional information about logging configuration can be found here:
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 |
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. |
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.
Property | Description | Required | Values/Examples | |
|---|---|---|---|---|
Configuration parameters | ||||
TransportLayer.TransportAdapters | The list of user-defined Transport Adapter names. The several instances should be separated by a comma
| No | ||
TransportLayer.RestOutTA.Description | The description of the adapter. This information is shown in Monitoring API | Yes | REST Initiator Client | |
TransportLayer.RestOutTA.DllName | Path to Transport Adapter library | Yes | Linux:
Windows:
| |
TransportLayer.RestOutTA.Type | Transport Adapter library type
| No | Supported values:
| |
TransportLayer.RestOutTA.ClientID | User defined id/name for referencing to Transport Adapters in Business Logic configuration | Yes | RestInitiatorClient | |
TransportLayer.RestOutTA.LogCategory | Transport adaptor log category. | Yes | RestInitiatorClient | |
TransportLayer.RestOutTA.Protocol | Connection protocol | Yes | Supported values:
| |
TransportLayer.RestOutTA.ServerHost | The destination host or IP address for sending messages | Yes | ||
TransportLayer.RestOutTA.ServerPort | The Port for the destination host | Yes | ||
TransportLayer.RestOutTA.URI | URI for HTTP request.
| Yes | /messages | |
TransportLayer.RestOutTA.SendingTimeout | Time (in seconds) for waiting for the response. After this time the adapter tries next time to start a connection. The maximum value may be limited by Operating System. | No | Default value = 0 - no timeout | |
TransportLayer.RestOutTA.SendingMaxAttempts | Number of connection attempts | No | Default value = 2 | |
TransportLayer.RestOutTA.ConversionMethod | The conversion method is the way the outgoing message is converted | Yes | Supported values:
| |
TransportLayer.RestOutTA.ResendMessageOnServerError | Controls undelivered message resending in the case of an error received from the server.
| Yes | Default value = False | |
TransportLayer.RestOutTA.ErrorCodesForUnDeliveredEvent | String parameter with a comma-separated list of error codes that generates an OnUndeliveredMessageEvent event and prevents resending. | Yes | Default value = 503 (Service Unavailable), 504 (Gateway Timeout) The list can be empty. | |
Proxy connection parameters | ||||
TransportLayer.RestOutTA.ProxyHost | Proxy host | No | ||
TransportLayer.RestOutTA.ProxyPort | Proxy port | Conditional | ||
TransportLayer.RestOutTA.ProxyLogin | Proxy user name | No | ||
TransportLayer.RestOutTA.ProxyPassword | Proxy user password | Conditional | ||
Validation parameters | ||||
TransportLayer.RestOutTA.ValidateFIXMessage | Enables/disables validation of FIX message
| No | Supported values:
| |
Security parameters | ||||
TransportLayer.RestOutTA.HTTPS.PrivateKey | path to the private key file | Conditional Mandatory if | ||
TransportLayer.RestOutTA.HTTPS.Certificate | path to certificate key file | Conditional | ||
TransportLayer.RestOutTA.HTTPS.PrivateKeyPassword | password for encrypted private key file | No | ||
TransportLayer.RestOutTA.authHeader | The HTTP header name for authentication. All outgoing requests will contain the HTTP header with the value of the parameter. | No | ||
TransportLayer.RestOutTA.authValue | Authentication value in HTTP header | No |
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 |
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 -
On the picture below the configuration with two Rest Initiator adapters is shown (RestOutTA1 and RestOutTA2).
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> |
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 |
Message is not sent, adapter is initiated correctly, user gets error in REST TA log file:
2019-10-24 06:46:21,622 UTC DEBUG [RestInitiatorClient1] 27532 sendRequest attempt 1 of 2 |
In FIXEdge.log:
2019-10-24 06:46:21,631 UTC ERROR [RestOutTA] 27532 Error in sendToClient: Client 'RestInitiatorClient1' could not send POST request to the server (2) 'jsonplaceholder.typicodes.com'. Reason: Host not found: jsonplaceholder.typicodes.com. |
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.
Message is not sent, adapter is initiated correctly, user gets error in REST TA log file:
2019-10-24 07:17:05,706 UTC DEBUG [RestInitiatorClient1] 24408 sendToClient started |
A possible reason is wrong URI. If the URI value is correct, contact Support. Otherwise, correct the TransportLayer.RestOutTA.URIparameter value in adapter configuration.
User gets validation error, but message is sent successfully:
2019-10-24 08:19:25,663 UTC DEBUG [RestInitiatorClient1] 31516 sendToClient started |
User gets validation error, message is rejected:
2019-10-24 08:22:27,526 UTC DEBUG [RestInitiatorClient1] 34024 sendToClient started |
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:
TransportLayer.RestOutTA.ValidateFIXMessage = No). Message is not sent, adapter is initiated correctly, user gets error in log:
2019-10-24 08:36:44,231 UTC DEBUG [RestInitiatorClient1] 22820 sendToClient started |
or:
019-10-30 06:23:10,941 UTC DEBUG [RestInitiatorClient1] 24840 Setting up HTTP session with jsonplaceholder.typicode.com:443 endpoint |
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.