Документация содержит описание продукта HyperHive версии 2.0.12 (стр. 11 )

Основные особенности выполнения быстрого метода:

метод выполняется в UI-потоке; запрос выполняется только синхронно; результат выполнения запроса (если он имеется) возвращает метод.

5.1.2 Аутентификация и метод его получения

Для работы с API-http необходимо сначала пройти аутентификацию с помощью API-метода auth. Остальные методы API не принимают логин и пароль. Если в запросе нет куки с валидным api_sessionid, то они возвращают ошибку 401.

Метод/auth

Запрос

HTTP-метод: GET.

URL: /api/v0.6/auth/?env=<env>&proj=<proj>&app=<app>.

Входные параметры:

название среды; название проекта; название версии проекта (для обращения через API используется параметр: app); логин; пароль.

Параметры можно передавать в одном из двух режимов:

с использование GET-параметров. Пример:

URL: /api/v0.6/auth/?env=<env>&proj=<proj>&app=<app>; логин для базовой авторизации: <login>; пароль для базовой авторизации: <password>;

с использованием полного логина. Пример:

URL: /api/v0.6/auth/; логин для базовой авторизации: <env>/<proj>/<app>/<login>; пароль для базовой авторизации: <password>.

Рекомендуется использовать первый способ. Второй реализован для совместимости с клиентами WebDAV.

Если пользователь уже аутентифицирован, т. е. он передает куку api_sessionid с валидным токеном, то метод возвращает такой же ответ, как в при успешной аутентификации.

Ответ об успешной аутентификации

Код: 200 OK.

Заголовки: кука "api_sessionid" с токеном.

Тело сообщения: JSON с токеном.

Пример ответа:

{"api_sessionid": "abcdef"}

Ответ об ошибке авторизации

Код: 401 Unauthorized.

Тело сообщения: описание ошибки в формате JSON.

{ "code": 401, "description": "Unauthorized" }

5.1.3 Специальные заголовки

X-Delta

Этот заголовок используется для указания версий дельты в запросе.

Значение заголовка должно содержать обозначение версий дельты.

В ответе название конечной версии должно быть указано в заголовке Content-Version. Версия в ответе должна быть указана явно, т. е. без слова last.

Пример использования:

> GET /api/v0.6/table/fruits > X-Delta: v0-last > ... < HTTP/1.1 200 OK < Content-Version: "delta v0-v6" < ... < < [[1, "Апельсин"]]

Х-Data-Range

Кастомный заголовок X-Range работает так же как Range, кроме следующих моментов:

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

Пример заголовков в запросе и ответе:

Запрос	Ответ
Accept-Encoding: gzip X-Range: bytes=123- If-Match: "1a2b3c"	Content-Encoding: gzip Content-Range: bytes 123-/* ETag: "1a2b3c" Trunsfer-Encoding: chunked

X-Device-Id

Если в запросе передан заголовок X-Device-Id, то в случае успешной аутентификации в базе данных будет создано устройство (если оно не было создано ранее) и привязано к текущему пользователю.

5.1.4 Метод получения описания ресурсов (/resources_description)

Запрос

HTTP-метод: GET.

URL: /api/v0.6/resources_description/.

Требует авторизации по api_sessionid.

Ответ

Код: 200 OK.

Тело сообщения: перечень ресурсов с описанием структуры в формате JSON.

Перечень ресурсов в ответе содержит ресурсы, к которым есть доступ у пользователя API (доступ к ресурсам фиксируется в присвоенной группе). Если в группе есть только разрешенные ресурсы, без зафиксированного параметра: Учетные данные, то разрешенные ресурсы все равно попадут в ответ.

Таким образом, следует помнить, что параметр Учетные данные (при создании учетной записи мобильного пользователя и группы) не влияет на доступ к списку ресурсов.

5.1.5 Метод работы с табличными ресурсами (/table/<resources>)

Табличный ресурс

Скалярный тип данных – это простой тип данных, например, "целое число", "текст" и т. д.

Табличный тип данных – это тип данных, которые являются таблицей из именованных колонок скалярного типа.

Табличный ресурс – это ресурс в платформе HyperHive, который возвращает одну таблицу.

Источник табличных данных – это источник данных, с которыми можно работать через табличный ресурс.

Табличный ресурс в платформе HyperHive может иметь входные параметры, которые должны удовлетворять следующим требованиям:

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

Концепция метода работы с табличными ресурсами

Это API для запроса табличных ресурсов.

В запросе ресурсу можно передать параметры. В ответе ресурс вернет таблицу. Поддерживается два вида ответов:

ответ с полной таблицей – таблица возвращается целиком в формате JSON; ответ с дельтой – возвращается дельта между двумя версиями в формате JSON или TableStream.

Вид ответа задается в запросе с помощью заголовков X-Delta.

Запрос

Методы: POST.

URL: /api/v0.6/table/<resource>.

Заголовок X-Delta определяет вид ответа: с полной таблицей или с дельтой. Если заголовка нет, то ответ должен быть с полной таблицей. Если есть, то ответ должен быть с дельтой.

Заголовок Content-Type задает формат ответа c дельтой. Если значение заголовка "application/x-tablestream", то дельта должна быть в формате TableStream v0.2. В других случаях ответ должен быть в формате JSON.

Тело запроса: параметры табличного ресурса в формате JSON.

Если параметры ресурса не указаны, то будут использованы значения по-умолчанию. Для скалярных параметров они задаются в админке. Для табличных параметров значением по-умолчанию является пустая таблица, т. е. таблица с нулем строк.

Ответ с полной таблицей

Код oтвета: 200 OK.

Тело ответа: строки таблицы в формате JSON.

Ответ с дельтой

Код oтвета: 200 OK.

Тело ответа: дельта таблицы в формате JSON или TableStream v0.2.

Формат задается в запросе в заголовке Content-Type.

Логика формирования отчета

Ответ формируется в соответствии с диаграммой.

Формат TableStream v0.2

TableStream – формат для потоковой передачи дельты таблиц. Разработан как замена JSON, так как JSON не ориентирован на потоковую передачу данных.

Описание

Cинтаксис сообщения TableStream в нотации ABNF:

message = *(command_insert SEP) *1(command_delete SEP)

SEP = %xFF CRLF

Значение разделителя 0xFF выбрано так, чтобы такого байта не могло быть в кодировке UTF-8 (см. стр. 126).

Значения токенов command_insert и command_delete являются валидной JSON-строкой.

Пример команды command_insert:

{"insert_row": [1, "Апельсин"]}

Пример команды command_delete:

{"delete_ids": [1, 2, 3]}

Примеры

Пример сообщения, которое добавляет две строки и удаляет 3:

{"insert_row": [1, "Апельсин"]}

{"insert_row": [2, "Банан"]}

{"delete_ids": [3, 4, 5]}

Пример сообщения, которое добавляет 1 строку и удаляет 0:

{"insert_row": [1, "Апельсин"]}

Пример сообщения, которое добавляет 0 строк и удаляет две строки:

{"delete_ids": [1, 2]}

Использование вместе с HTTP

Для использования TableStream поверх HTTP клиент и сервер должны в качестве Content-Type использовать "application/x-tablestream".

5.1.6 Метод работы с Web-ресурсом

URL: /api/v0.6/web/<resource>.

Проксирование HTTP-запросов на другой сервер.

5.1.7 Метод работы с WebDAV

URL: /api/v0.6/webdav/<resource>.

Короткое описание

Позволяет делать запросы по протоколу WebDAV. Поддерживается чтение и запись файлов и другие возможности протокола.

Запрос

Поддерживаемые методы: PUT, DELETE, MKCOL, PROPFIND, OPTIONS.

PUT – Выгрузить файл на сервер;
DELETE – Удалить файл с сервера;
MKCOL — Создать коллекцию объектов (каталог в случае доступа к файлам);
PROPFIND — Получение свойств объекта на сервере в формате XML. Также можно получать структуру репозитория (дерево каталогов);

Есть два способа аутентификации:

Стандартный. Можно использовать куку session_id из метода /auth. Однако, большинство WebDAV клиентов так не умеют; Полный логин. При работе с этим API можно использовать базовую аутентификацию с расширенным логином. Этот метод описан в документации на /auth.

Совместимость

Реализация протокола WebDAV cовместима с клиентом cadaver, и не совместима со стандартным клиентом Windows.

Пример использования cadaver:

$ cadaver http://hhive. local/api/v0.6/webdav/my_res/

Username:

my_env/my_proj/my_app/my_login

Password:

dav:/api/v0.6/webdav/my_res/>

5.1.8 Метод работы с MS Exchange

Получение данных от MS Exchange.

URL: /api/v0.6/exchange/<resource>.

5.1.9 Методы работы с логами

Метод /logs/push

Запрос

Методы: POST.

URL: /api/v0.6/logs/push/.

Тело запроса: список логов в формате JSON.

Ответ

При удачном добавлении логов:

{"status": "OK"}

Метод /logs/schedule

Запрос

Запрашивает на сервере настройки хранения логов.

Методы: GET.

URL: /api/v0.6/logs/schedule/.

Ответ

Описание расписания в формате JSON. Пример:

{

  "trim": true,

  "schedule": "0 * 0 0 0 (m/h/dM/MY/dw)"