Структуры данных¶

Для сериализации/десериализации структур данных, передаваемых в HTTP запросах и ответах, составляющих интеграторский интерфейс Диадока, можно использовать следующие механизмы:

По умолчанию все структуры ожидаются в формате Protocol Buffers, так как он считается основным форматом для передачи данных.

Мы рекомендуем для интеграционных решений использовать формат Protocol Buffers, так как у него есть ряд преимуществ по сравнению с форматом JSON - одно из основных это обратная совместимость.

В JSON поддерживаются только последние версии структур данных.

Прежде чем выбирать формат передачи данных, рекомендуем ознакомиться с данной статьей - http://blog.codeclimate.com/blog/2014/06/05/choose-protocol-buffers/

Google Protocol Buffers¶

Описание синтаксиса языка Protocol Buffers можно посмотреть здесь.

Для различных платформ и языков программирования существуют уже готовые библиотеки, решающие задачу сериализации/десериализации родных структур данных в протобуферы. Вот некоторые из них:

C++, Java, Python - официальная реализация Google;
Microsoft® .NET - проект protobuf-net;
и другие - много ссылок.

Актуальная версия инструментария для разработчиков https://diadoc.kontur.ru/sdk/ также содержит все необходимые, для использования интеграторского интерфейса Диадока, библиотеки.

JSON¶

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

Заголовок Accept: application/json - указывается для получения структур в формате JSON в теле ответа,
Заголовок Content-Type: application/json; charset=utf-8 - указывается для передачи структур в формате JSON в теле запроса,

По умолчанию, состав всех структур в обоих форматах одинаков, если не сказано обратного.

Бинарный контент следует передавать с помощью base64 - строк.

Пример описания¶

Например, если SearchDocflowsRequest можно описать следующим образом.

В формате Protocol Buffers:

message SearchDocflowsRequest
{
    required string QueryString = 1;
    optional int32 Count = 2 [default = 100];
    optional int32 FirstIndex = 3;
    optional SearchScope Scope = 4 [default = SearchScopeAny];
    optional bool InjectEntityContent = 5 [default = false];
}

enum SearchScope
{
    SearchScopeAny = 0;
    SearchScopeIncoming = 1;
    SearchScopeOutgoing = 2;
    SearchScopeDeleted = 3;
    SearchScopeInternal = 4;
}

В формате JSON:

{
    "QueryString": "example",
    "Count": 100,
    "FirstIndex": 1,
    "Scope": 0,
    "InjectEntityContent": false
}