Skip to main content

HTTP API syntax

Application programming interfaces allow the API user to address the server with various commands aimed at obtaining information or performing some actions by the server. However, it should be taken into account that these commands should be understandable to the server and therefore they should be composed according to the predefined syntax.

Components​

According to RFC 7230, and its successor standards RFC 9110 and RFC 9112, each HTTP request can be partitioned into the following constituent parts:

tip

Query and Body parameters are interchangeable and can take an empty value depending on the method of the query being executed (GET, PUT, POST, DELETE).

Header parameters​

Header parameters are used to pass to the API server service information about the request being executed: method and authorization data, format of data passed in the request or response, etc.

Header parameters for the HTTP protocol are standardized and listed in the specification RFC 4229.

Below are described Header parameters that you should pay attention to when working with ALOR Broker API.

Authorization​

The Authorization Header parameter is used to confirm the request sender's right to access the resource. Requests to the ALOR Broker API may affect segments of the system to which public access is prohibited for security reasons.

To authorize a request, add the following parameter to its header:

Authorization: Bearer {Token}

Where {Token} is the valid Access Token of the API user.

tip

It is recommended to perform authorization even for those requests that support anonymous sending. This will avoid restrictions imposed by the system on anonymous requests.

X-REQID​

The X-REQID Header parameter is used to pass a unique identifier of the object being created or modified by the request. This parameter is mainly used when working with orders via API.

To set the object identifier, add the following parameter to the request header:

X-REQID: {GUID}

Where {GUID} is a unique identifier of the object passed to the server by the API user.

tip

The system assigns to objects the GUID that was passed in the resource request. GUID generation must be performed by the API user.

Request URL​

Each request to the HTTP API, regardless of the chosen interaction method, must contain the URL of the resource to which the request is directed. The request URI can be represented as follows:

{protocol}://{server address}/{Path}?{Query}

Where:

  • {protocol} is the protocol for communicating with the server (HTTP, HTTPS).
  • {server address} is API server address.
  • {Path} is Path parameters of the requested resource.
  • {Query} is Query parameters supported by the requested resource.
note

For security reasons, the HTTP API of the ALOR Broker trading system accepts requests and transmits information only via the secure HTTPS protocol.

The above described request structure is followed in all HTTP requests without exception, the only difference may be the number of parameters within one URL and their values.

Example

The URL of the request for All security trades for today looks like this:

https://api.alor.ru/md/v2/Securities/MOEX/SBER/alltrades?format=Slim

Where:

  • https:// is the protocol of communication with the server.
  • https://api.alor.ru is the address of the API server of the ALOR Broker trading system Production environment.
  • /md/v2/Securities/MOEX/SBER/alltrades are Path parameters of the requested resource.
  • format is one of the Query parameters supported by the requested resource.

Path parameters​

Path parameters are part of the URL request to the API and are used to specify the exact path to a particular resource endpoint.

According to URI syntax, Path parameters are all parameters located between the communication protocol and the ? sign that marks the beginning of the Query parameters segment.

For example, the query:

https://api.alor.ru/md/v2/Securities

Can be expressed as:

https://api.alor.ru/{Path1}/{Path2}/{Path3}
note

According to the HTTP specification, the server address given in the URL of a request is also a Path parameter (the so-called "base address"). Despite this, in future it will be discussed as a standalone entity in this manual.

When forming a URL request, each of the Path parameters corresponds to one of the levels of the API resource being called, so each subsequent parameter can be considered a component of the previous one.

For example, the query:

https://api.alor.ru/md/v2/Securities

Can be structurally represented as a request to the Securities resource, which is a component of the v2 resource, which is in turn a component of the md resource.

https://api.alor.ru
└─ md
   └─ v2
      └─ Securities

According to the HTTP specification, all Path parameters in a URL request are dynamic by default, allowing them to be used as variables to pass changing values to the API server.

Example:

https://api.alor.ru/md/v2/Securities
https://api.alor.ru/commandapi/api/orderGroups

The above queries use different Path-parameters to access different resources through the same base address. Structurally, these requests will look as follows:

https://api.alor.ru
├─ md
|  └─ v2
|     └─ Securities
└─ commandapi
   └─ api
      └─ orderGroups

However, in the description of each individual request, this guide allows Path parameters to be categorized by the way the values are assigned:

  • Static — the value is predefined by the system architecture and is constant for all requests to the specified endpoint.
  • Dynamic — the value is arbitrary and must be set by the API user.

In query descriptions, dynamic path parameters are written in curly braces ({ and }). When the query is executed, they will be replaced by the actual value of the parameter.

For example:

https://api.alor.ru/md/v2/Securities/{exchange}

The Securities parameter in the request above is a static pointer, unchanged for all requests to the endpoints of this resource, while the {exchange} parameter allows the API user to set the value themselves to address the needed endpoint.

The dynamic parameter {exchange} in this request specifies the exchange from which we need to get information (MOEX, SPBX). The parameter designation must be replaced with its actual value when executing the request:

https://api.alor.ru/md/v2/Securities/MOEX
tip

The number of Path parameters and the order in which they are placed in the URL of the request depends on the architecture of each individual resource. The full list of Path parameters for the selected endpoint is available on the corresponding request description page in the HTTP API section.

Query parameters​

tip

Usable in GET and DELETE queries.

Query parameters, like Path parameters, are part of the Request URL to the API, but are used to pass additional (mostly optional) parameters to specify the conditions for the server to process the received command.

note

POST and PUT requests pass additional parameters using Body parameters.

According to URI syntax, Query parameters must be placed in the URL after the ? sign indicating the beginning of the segment, and must be delimited from each other by the & character. Both in the request description and during its execution, Query parameters have the key={value} structure, where key corresponds to the name of the parameter and {value} to its value.

For example:

https://api.alor.ru/md/v2/Securities/MOEX?format=Slim

The above request contains a query parameter format with the Slim value, where:

  • format — the desired presentation format of the response from the server.
  • Slim — lightweight presentation format.

Unlike Path parameters, query parameters can be placed in a URL within its segment in any order without affecting the result.

tip

A complete list of Query parameters for the selected endpoint is available on the corresponding request description page under HTTP API section.

Body parameters​

tip

Usable in POST and PUT queries.

Body parameters like Query parameters extend the request with additional information for the server. These parameters are located not in the URL of the request, but in the message body that should be passed with it. The purpose of using body parameters is to provide the system with information to create or modify objects stored on the server.

note

In GET and DELETE queries additional parameters can be passed using Query parameters.

Regardless of their number, Body parameters are always sent to the server as an array of data structured according to the chosen format (for ALOR Broker API it is always JSON). In this regard, the general syntax of the message in the request body looks as follows:

{
  "key": "value"
}

Where:

  • key is the parameter name
  • value is the parameter value
Example

When sending the Create Market order request, the server expects the following message in the request body:

{
  "side": "buy",
  "type": "market",
  "quantity": 1,
  "instrument": {
    "symbol": "SBER",
    "exchange": "MOEX"
  },
  "comment": "First order",
  "user": {
    "portfolio": "D39004"
  }
}

Where:

  • side is the direction of the transaction
  • type is the type of order
  • quantity is the number of lots
  • instrument is an array with information about financial instrument. Includes:
    • symbol which is a financial instrument code (ticker)
    • exchange which is the code of the exchange
  • comment is user comment to the order
  • portfolio is client portfolio identifier

Keep in mind that the server expects to receive complete information about the object being created or modified, so the message sent to the endpoint must contain all Body parameters listed on the description page of the resource being called, and their values must be unambiguously interpretable by the server.

For example, the side parameter from the above message can take only two values — buy or sell — according to the direction of the transaction in the market order being created. Any other values of this parameter or its absence in the message will cause an error when executing the request.

tip

A complete list of Query parameters for the selected endpoint is available on the corresponding request description page under HTTP API section.