Перейти к основному содержимому

Синтаксис HTTP API

Интерфейсы программного взаимодействия позволяют пользователю API обращаться к серверу с различными командами, направленными на получение информации или выполнение сервером каких-либо действий. Однако стоит учитывать, что эти команды должны быть понятны серверу и потому их необходимо формировать в соответствии с заранее определённым синтаксисом.

Компоненты запроса​

Согласно стандарту RFC 7230, а также пришедшим ему на смену стандартам RFC 9110 и RFC 9112, каждый HTTP-запрос можно разделить на следующие составные части:

подсказка

Query- и Body-параметры являются взаимозамещающими и могут принимать пустое значение в зависимости от метода выполняемого запроса (GET, PUT, POST, DELETE).

Header-параметры​

Header-параметры, называемые также параметрами заголовка, используются для передачи серверу API служебной информации о выполняемом запросе: способ и данные авторизации, формат передаваемых в запросе или ответе данных и т.д.

Параметры заголовка для протокола HTTP стандартизированы и перечислены в спецификации RFC 4229.

Ниже описаны Header-параметры, на которые стоит обратить внимание при работе с АЛОР Брокер API.

Authorization​

Header-параметр Authorization используется для подтверждения личности отправителя запроса. Запросы к АЛОР Брокер API могут затрагивать сегменты системы, публичный доступ к которым запрещён из соображений безопасности.

Для авторизации запроса добавьте в его заголовок следующий параметр:

Authorization: Bearer {Token}

Где {Token} — действующий Access Токен пользователя API.

подсказка

Авторизацию рекомендуется выполнять даже для тех запросов, которые поддерживают анонимную отправку. Это позволит избежать ограничений, накладываемых системой на анонимные запросы.

X-ALOR-REQID​

Header-параметр X-ALOR-REQID используется для передачи в запросе уникального идентификатора создаваемого или изменяемого объекта. Этот параметр заголовка применяется преимущественно при работе с заявками через API.

Для указания идентификатора объекта добавьте в заголовок запроса следующий параметр:

X-ALOR-REQID: {GUID}

Где {GUID} — уникальный идентификатор объекта, передаваемого серверу пользователем API.

подсказка

Система присваивает объектам тот GUID, который был передан в запросе к ресурсу. Генерация GUID выполняется пользователем API.

URL запроса​

Каждый запрос к HTTP API, независимо от выбранного метода взаимодействия, должен содержать URL ресурса, к которому направлен запрос. URI запроса можно представить следующим образом:

{протокол}://{адрес-сервера}/{Path}?{Query}

Где:

  • {протокол} — протокол взаимодействия с сервером (HTTP, HTTPS).
  • {адрес-сервера} — адрес сервера API.
  • {Path} — Path-параметры запрашиваемого ресурса.
  • {Query} — Query-параметры, поддерживаемые запрашиваемым ресурсом.
примечание

Из соображений безопасности HTTP API торговой системы АЛОР Брокер принимает запросы и передаёт информацию только по защищённому протоколу HTTPS.

Описанная выше структура запроса соблюдается во всех HTTP-запросах без исключения, различие может заключаться только в количестве параметров в рамках одного URL и их значения.

Пример

URL запроса Получение информации о всех сделках по ценным бумагам за сегодня при выполнении выглядит следующим образом:

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

Где:

  • https:// — протокол общения с сервером.
  • api.alor.ru — адрес сервера API боевого контура торговой системы АЛОР Брокер.
  • /md/v2/Securities/MOEX/SBER/alltrades — Path-параметры запрашиваемого ресура.
  • format — один из Query-параметров, поддерживаемых запрашиваемым ресурсом.

Path-параметры​

Path-параметры, называемые также параметрами пути, являются частью URL запроса к API и используются для указания точного пути к определённой конечной точке ресурса.

Согласно синтаксису URI, параметрами пути являются все параметры, расположенные между указанием протокола взаимодействия и знаком ?, обозначающим начало сегмента Query-параметров.

Например, запрос:

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

Можно выразить как:

https://api.alor.ru/{Path1}/{Path2}/{Path3}
примечание

Согласно спецификации HTTP, адрес сервера, указываемый в URL запроса, также является Path-параметром (т.н. "базовый адрес"). Несмотря на это, в дальнейшем он будет рассматриваться в данном руководстве как отдельная сущность.

При формировании URL запроса каждый из Path-параметров соответствует одному из уровней вызываемого ресурса API, в связи с чем каждый последующий параметр можно считать одним из компонентов предыдущего.

Например, запрос:

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

Можно структурно представить как обращение к ресурсу Securities, являющемуся компонентом ресурса v2, являющегося в свою очередь компонентом ресурса md.

api.alor.ru
└─ md
   └─ v2
      └─ Securities

Согласно спецификации HTTP, все Path-параметры в URL запроса по умолчанию являются динамическими, позволяя использовать их как переменные для передачи изменяемых значений серверу API.

Например:

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

В представленных выше запросах используются разные Path-параметры, позволяющие обращаться к разным ресурсам через один и тот же базовый адрес. Структурно же эти запросы будут выглядеть следующим образом:

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

Тем не менее, при описании каждого отдельного запроса данное руководство допускает разделение Path-параметров по способу присвоения значений на:

  • Статические — значение предопределено архитектурой системы и неизменно для всех обращений к указанной конечной точке.
  • Динамические — значение должно быть задано пользователем API.

В описании запросов динамические параметры пути записываются в фигурных скобках ({ и }). При выполнении запроса их место занимает фактическое значение параметра.

Например:

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

В представленном выше запросе параметр Securities является статическим указателем, неизменным для всех запросов к конечным точкам этого ресурса, тогда как параметр {exchange} позволяет пользователю API самостоятельно задать значение для обращения к нужной конечной точке.

Динамический параметр {exchange} в данном запросе указывает биржу, от которой необходимо получить информацию (MOEX, SPBX). При выполнении запроса обозначение параметра должно быть заменено на его фактическое значение:

https://api.alor.ru/md/v2/Securities/MOEX
подсказка

Количество Path-параметров и порядок их размещения в URL запроса зависят от архитектуры каждого отдельного ресурса. Полный список Path-параметров для выбранной конечной точки доступен на странице описания соответствующего запроса в разделе HTTP API.

Query-параметры​

подсказка

Применяются в запросах с методами GET и DELETE.

Query-параметры, называемые также параметрами запроса, как и Path-параметры, являются частью URL запроса к API, но используются для передачи дополнительных (преимущественно, опциональных) параметров для уточнения условий обработки сервером поступившей команды.

примечание

В запросах с методами POST и PUT передача дополнительных параметров осуществляется с помощью Body-параметров.

Согласно синтаксису URI, параметры запроса размещаются в URL после знака ?, обозначающего начало сегмента, и отделяются друг от друга символом &. Как в описании запроса, так и при его выполнении Query-параметры имеют структуру key={value}, где key соответствует имени параметра, а {value} — его значению.

Например, запрос:

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

Содержит параметр запроса format со значением Slim, где:

  • format — желаемый формат представления ответа от сервера.
  • Slim — облегчённый формат представления.

В отличии от Path-параметров, параметры запроса могут размещаться в URL в рамках своего сегмента в любом порядке без влияния на результат.

подсказка

Полный список Query-параметров для выбранной конечной точки доступен на странице описания соответствующего запроса в разделе HTTP API.

Body-параметры​

подсказка

Применяются в запросах с методами POST и PUT.

Body-параметры, называемые также параметрами тела запроса, как и Query-параметры расширяют запрос дополнительной информацией для сервера, но располагаются не в URL запроса, а в передаваемом вместе с ним теле сообщения. Целью использования параметров тела запроса является передача серверу информации для создания и изменения хранящихся на сервере объектов.

примечание

В запросах с методами GET и DELETE передача дополнительных параметров осуществляется с помощью Query-параметров.

Независимо от их количества, Body-параметры всегда передаются серверу в виде массива данных, структурированных в соответствии с выбранным форматом (для АЛОР Брокер API — всегда JSON). В связи с этим общий синтаксис сообщения в теле запроса выглядит следующим образом:

{
    "key": "value"
}

Где:

  • key — имя параметра
  • value — значение параметра
Пример

При передаче запроса Создание рыночной заявки сервер ожидает в теле запроса сообщение следующего образца:

{
  "side": "buy",
  "type": "market",
  "quantity": 1,
  "instrument": {
    "symbol": "SBER",
    "exchange": "MOEX"
  },
  "comment": "Первая заявка",
  "user": {
    "portfolio": "D39004"
  }
}

Где:

  • side — направление сделки
  • type — тип заявки
  • quantity — количество лотов
  • instrument — массив с информацией о финансовом инструменте. Включает в себя:
    • symbol — код финансового инструмента (тикер)
    • exchange — код биржи
  • comment — пользовательский комментарий к заявке
  • portfolio — идентификатор клиентского портфеля

Стоит учитывать, что сервер ожидает получить полную информацию о создаваемом или изменяемом объекте, в связи с чем отправляемое к конечной точке сообщение должно содержать все Body-параметры, перечисленные на странице описания вызываемого ресурса, а их значения должны быть однозначно интерпретируемы сервером.

Так, например, параметр side из приведённого выше сообщения может принимать только два значения — buy (покупка) и sell (продажа) — по направлению сделки в создаваемой рыночной заявке. Любые другие значения этого параметра или его отсутствие в сообщении приведут к ошибке при выполнении запроса.

подсказка

Полный список Query-параметров для выбранной конечной точки доступен на странице описания соответствующего запроса в разделе HTTP API.