Introduction to Reporting API
The Reporting API is a versatile and easy-to-use solution that allows for integrating your reporting systems with the cTrader backend. You can also use it as a basis for developing a custom reporting suite. The Reporting API provides you with data about key server entities (e.g., traders, orders, and positions) that you can process using any suitable logics.
If you are a non-broker entity, you cannot work with white labels through the Reporting API. Please use other APIs or contact us at partners@spotware.com for clarifications.
Google Protobufs and RabbitMQ
Similarly to the Manager's API, the Reporting API uses Google Protocol Buffers (Protobufs) as a means of transferring information between services.
The Reporting API uses syntax version 2 (Proto2). When selecting a language/library for integration, make sure that it supports this version.
A detailed guide to working with with Protobufs can be found in our introduction to the Manager's API. Additional information can also be found on the following resources.
For sending real-time data, the Reporting API uses RabbitMQ, a well-known message broker.
Key Components and Use Cases
Integration with the Reporting API is recommended in case you need to achieve any of the following goals.
- Creating a custom in-house reporting system displaying statistics originating from cTrader accounts.
- Making sure an existing reporting solution can receive and process information from the cTrader backend.
To attain these goals, the Reporting API consists of two key components.
- Snapshots. These are received by performing web requests to certain endpoints.
- Events. As stated previously, events are received after establishing a connection with RabbitMQ.
A snapshot provides information about the state of certain server entities during the specified period. Depending on the request you make, a snapshot may either contain a list of entities and their attributes, or data about just one entity.
In contrast, events act as notifications about the creation/modification/deletion of server entities. Each event is preceded by a sequence number allowing you to detect cases where reconciliation with the cTrader backend may be required. Finally, spot events represent changes in bid/ask prices.
Snapshots are time and resource-consuming to take. In most cases, it is necessary to only take snapshots at the initial stages of integration so that you can receive information about the entire structure of the database. Snapshots should also be taken for reconciliation in case you detect that you have not received or processed any real-time events. Ideally, snapshots should be taken during weekends.
When generating sequence numbers for real-time events, each server restart produces a new sequence starting from 1. As a result, please follow the below rules when deciding whether reconciliation is needed.
1. If you receive events whose sequence numbers are incremented by 1 with each consecutive event (e.g., 23456, 23457, 23458), no reconciliation is needed.
2. If you receive events whose sequence numbers are incremented by 1 and then receive an event whose sequence number is 1, a server restart has occurred and reconciliation is needed.
3. If you receive events whose sequence numbers are incremented by a number larger than 1 (e.g., 23456, 23458, 23463), some events have been missed and reconciliation is needed.
The Reporting API vs the Manager's API
Both the Reporting API and the Manager's API are powerful tools that could be used for receiving statistics from the cTrader backend.
Compared to the Manager's API, the Reporting API has several characteristics that limit its functionality to just reporting. The following table summarizes the main differences between the APIs.
| Characteristic | Manager's API | Reporting API |
|---|---|---|
| Authorization/authentication mechanism | Each participant has to be authorized using a special manager's token which can only be received after gaining access to the cTrader Admin back office. | There are no additional authorization/authentication mechanisms. The full functionality can be accessed by any manager from any business entity that has access to your server and knows the API connection details. |
| Access rights | Each participant can only perform actions that they have specifically been granted permissions to perform in the cTrader Admin back office. | Each participant can always perform all actions that are permitted by the API. |
| Possible actions | Participants can receive statistics, manage trading conditions, oversee accounts, etc. | Participants can only receive statistics. |
As a result, integration with the Manager's API is preferable in the following cases.
- You have a server with several small-scale White Labels (WLs) and you want to minimise risks by separating the access rights of their managers.
- You want to not only receive statistics but also to create a custom system for controlling accounts, symbols, assets, liquidity feeds, and other major server entities.
In any other case, integration with the Reporting API is a valid alternative.
Structure of the Documentation
Apart from this introduction, the documentation is divided into the following sections.
Protobuf Files
You can access the latest verion of the Reporting API Protobuf files here.