Serialising and Deserialising Messages¶

To serialise/deserialise messages sent to and from the cTrader backend, you can use either Protocol Buffers (Protobufs) or JSON (JavaScript Object Notation).

Below, we define each method of serialisation/deserialisation in detail.

JSON¶

JSON objects can be defined as simple key-value pairs. Note that keys are always strings while values can be of different data types as shown in the below example.

{
    "clientMsgId": "cm_id_2",
    "payloadType": 2100,
    "payload": {
        "keyOne": [1, 2, 10,],
        "keyTwo": "valueTwo",
    }
}

In the example, the value of the "clientMsgId" key is a string while the value of the "payloadType" key is an integer. The "payload" key contains another JSON object which is nested in the body of the 'parent' object. The value of the "payload.keyOne" key is a list of integers.

For a tutorial on how you can send/receive JSON, click here.

Protocol Buffers¶

Protocol Buffers (or Protobufs) offer a language and platform-neutral, extensible mechanism for serialising structured data. By using Protobufs, you can encode structured data in an efficient yet extensible format.

With Protobufs, you only need to define how you want your data to be structured once. This is done by specifying Protobuf message types in .proto files.

Each Protobuf message is a record of information containing a series of name-value pairs. Below, you can find a basic example of a .proto file that defines a message containing information about a person.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

message Person {

    required string name = 1;  
    required int32 id = 2;  
    optional string email = 3;  


    enum PhoneType {  
        MOBILE = 0;  
        HOME = 1;  
        WORK = 2;  
    }  

    message PhoneNumber {  
       required string number = 1;  
       optional PhoneType type = 2 [default = HOME];  
    }  

    repeated PhoneNumber phone = 4;  
}

As you can see, the message format is simple. Each message type has one or more uniquely numbered fields, and each field has a name and a value type, where value types can be numbers (integer or floating-point), booleans, strings, raw bytes, or even (as in the example above) other Protocol Buffer message types, allowing you to structure your data hierarchically.

You can find more information about writing .proto files in the Protocol Buffer Language Guide.

You can learn more about Protocol Buffers here.

For a tutorial on sending/receiving Protobufs, click here.

ProtoMessages¶

When working with Protobufs, you will be sending and receiving ProtoMessage objects designed by Spotware.

To handle network fragmentation, sending messages uses the following frame structure.

1
2
3
4

 +--------------------------+-----------------------------------------+  
 | Message Length (4 bytes) | Serialized ProtoMessage object (byte[]) |  
 +--------------------------+-----------------------------------------+  
                            |<---------- Message Length ------------->|

Each ProtoMessage has the following structure.

1
2
3
4
5

 +----------------------+  
 | int32 payloadType    |  
 | byte[] payload       |  
 | string clientMsgId   |  
 +----------------------+

The structure contains two mandatory fields.

• payloadType. Contains the ProtoPayloadType ID. This field denotes the type of the Protobuf object serialised in the payload field.
• payload. Contains the actual serialised Protobuf message that corresponds to payloadType.

One other field is optional.

• clientMsgId. Contains the message ID which is assigned by the client.

The actual `ProtoMessage`` definition looks as follows.

1
2
3
4
5
6
7
8

message ProtoMessage {  
    required uint32 payloadType = 1; //Contains the ID of the ProtoPayloadType or other
    custom PayloadTypes (e.g. ProtoCHPayloadType).  
    optional bytes payload = 2; //The serialised Protobuf message that corresponds to
    the payloadType.  
    optional string clientMsgId = 3; //The request message ID which is assigned by the
    client.  
}

Naming Convention¶

The Protobuf messages that form the cTrader Open API can be categorised into the following types.

• Request messages
• Response messages
• Event messages
• Model messages

Request Messages¶

Request messages are used to ask the cTrader backend for information or perform various operations.

Request messages are marked with Req at the end of their respective names. For example, the ProtoOAAssetListReq message requests the cTrader backend to return a list of all assets available for trading to a currently authorised account.

Response Messages¶

Response messages mark data that is received from the cTrader backend.

Response messages are marked with Res at the end of their respective names. As an illustration, the ProtoOAAssetListRes message has a repeated field (asset) that contains all assets that the currently authorised account can trade.

Event Messages¶

Event messages asynchronously notify all their subscribers that a particular event has been triggered.

Event messages are marked with Event at the end of their respective names. For instance, the ProtoOAMarginChangedEvent is sent every time when the amount of margin allocated to a specific position is changed.

Model Messages¶

Model messages describe the entities that form the domain model in the cTrader backend.

The names of model messages always end with the name of the entity that they are defining. As an example, the ProtoOAAsset message defines the Asset entity.

Messages Repository¶

You can download the latest version of the cTrader Open API Protocol Buffers message files from this repository.

We recommend you follow the messages repository if you want to get notified whenever a new version of the message files is released.

Compiling Protobuf Messages¶

Once you attain the required Protobuf messages, you can run the Protobuf compiler for your chosen language on the .proto files defining these messages. On success, the compiler will generate data access classes in your preferred language.

These classes provide simple accessors for each field (such as name() and set_name()) as well as methods for handling serialisation and deserialisaition. The name of each class should match the full name of each message that was compiled. At this point, you can freely use the generated classes in your application to populate, serialise and deserialise Protobuf messages.

To learn more about compiling protobuf messages using your language of choice, click here.