Передача данных в API¶

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

По умолчанию структуры передаются и возвращаются в формате Protocol Buffers. Мы рекомендуем использовать в интеграционных решениях именно этот формат. Его основное преимущество по сравнению с форматом JSON — это обратная совместимость: в JSON поддерживаются только последние версии структур данных.

Перед выбором формата данных для своего интеграционного решения ознакомьтесь со статьей о сравнении этих форматов или другими ресурсами.

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

Все данные должны быть переданы в методы API в виде массива байт в формате base64.

Google Protocol Buffers¶

Синтаксис языка Protocol Buffers описан здесь.

Для различных платформ и языков программирования существуют готовые библиотеки для сериализации и десериализации данных в формат Protocol Buffers. Например:

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

SDK Диадока уже содержит все необходимые библиотеки для сериализации и десериализации данных в формат Protocol Buffers.

Пример¶

Данные объекта типа 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¶

Чтобы работать с данными в формате JSON, передайте в HTTP запросах к API Диадока следующие заголовки:

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

Пример¶

Объект типа SearchDocflowsRequest в формате JSON будет выглядеть следующим образом:

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