Передача данных в 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 }