Публичное API

Для реализации публичных методов API реализована авторизация через токен. Токен хранится в .env под названием PUBLIC_API_TOKEN.

Токен отображается в панели администрирования в разделе Системное – Обновление.

Какова схема авторизации

• При отправке запросов по урлам вида api/public/* идёт проверка на наличие Header-а x-auth-token. Если Header присутствует и соответствует указанному в конфиге, то авторизация проходит успешно.

• При отсутствии токена, либо если он указан неверно, возвращается ошибка 401 Authorization Required

Какие запросы можно использовать

Важно: При каждом обращении, не важно, POST или GET, в заголовках запроса нужно указывать параметр X-Auth-Token с предоставленным ключом в качестве значения.

Получение списка всех доступных отчётов

Чтобы получить список всех доступных Отчётов, нужно сделать GET запрос на адрес:

• GET /public/api/v1/reports/list
  без параметров (только с X-Auth-Token заголовком).

В ответ придёт JSON массив объектов, каждый из которых будет содержать Название (title) и Системное имя (type).

Получение метаданных

Чтобы получить метаданные о конкретном Отчёте, нужно сделать GET запрос на адрес:

• GET /public/api/v1/reports/metadata/<type>
  заменив в адресе <type> на нужное Системное имя, полученное на предыдущем этапе.

В ответ придёт JSON объект с двумя полями:

• headersList — объект, содержащий предполагаемые заголовки Отчёта;
  Количество полей может быть любое, зависит от отчёта, т.к каждый Отчёт содержет различные поля;
  Ключами являются Системные имена полей, а значениями являются Названия полей (например, "email": "Почта");
  В сформированном Отчёте может быть другое количество полей или их названия (например, в Отчёте по Тестированию могут быть поля,
  отвечающие за Вопросы выбранного Тестирования, но мы не можем знать эти Вопросы (поля) до выбора самого Тестирования, поэтому в метаданных этих полей заранее быть не может).

• filtersList — объект, содержащий Фильтры данного Отчёта;
  Ключами являются Системные имена, а значениями Объекты, с информацией о Фильтре (пример полей: type — тип, label — название, values — значения, url — адрес, на который нужно делать запрос для получения списка значений и поиска по нему);

Генерация и получение Отчёта

Обычный режим

Чтобы сгенерировать и получить Отчёт, нужно отправить POST запрос на адрес:

• post /public/api/v1/reports/generate/<type>
  заменив в адресе <type> на нужное Системное имя, полученное на этапе Получения списка всех доступных отчётов.

В body запроса нужно отправить JSON объект с полем filters, в котором будут поля, ключами которых будут Системные имена Фильтров, полученных на этапе Получения метаданных, а значениями непосредственно значения Фильтров (цифра, строка, массив и тд).

В ответ придёт JSON объект со следующими полями:

• title — строка с названием Отчёта;
  Может не совпадать со значением, полученным на первом этапе, т.к может содержать дополнительные данные вроде Даты и других значений.

• isMultiple — булево значение;
  Если значение true, то в полях headers и data будет не объект, а массив объектов - каждый объект это отдельная страница Отчёта.

• headers — объект, содержащий заголовки таблицы Отчёта, где ключи это Системные имена полей, а значения это Названия полей.

• data — массив объектов, содержащий данные Отчёта;
  Каждый объект в массиве - это одна строка;
  Каждый объект содержит поля, ключами которого являются Системные имена полей, а значениями являются данные (например, "status": "Активен").

• metadata — объект, содержащий дополнительные данные об Отчёте, например, выбранные Фильтры;
  Ключами объекта являются Системные имена полей, а значениями сами Данные (например, "metadataFieldName": "Тестовый пользователь").

• hasErrors — булево значение;
  Были ли ошибки при попытке сформировать Отчёт;
  Если значение true, значит Отчёт не сформирован и нужно смотреть ошибки в поле errors.

• errors — объект, содержащий ошибки;
  Ключами являются Системные имена полей, а значениями Текст ошибки.

Режим потокового скачивания

Чтобы сгенерировать Отчёт, для дальнейшего его скачивания в потоковом режиме, нужно отправить POST запрос на адрес:

• post /public/api/v1/reports/create/<type>
  заменив в адресе <type> на нужное Системное имя, полученное на этапе Получения списка всех доступных отчётов.

В ответ придёт JSON объект с полем id, он же Идентификатор сгенерированного отчета.

Чтобы получить JSON данные Отчёта, сгенерированного в предыдущем шаге, нужно отправить GET запрос на адрес:

• GET /public/api/v1/reports/data/<id>
  заменив в адресе <id> на нужный Идентификатор, полученный в предыдущем шаге

В ответ придёт JSON объект со следующими полями:

• title — строка с названием Отчёта;
  Может не совпадать со значением, полученным на первом этапе, т.к может содержать дополнительные данные вроде Даты и других значений.

• isMultiple — булево значение;
  Если значение true, то в полях headers и data будет не объект, а массив объектов — каждый объект это отдельная страница Отчёта.

• headers — объект, содержащий заголовки таблицы Отчёта, где ключи это Системные имена полей, а значения это Названия полей.

• data — массив объектов, содержащий данные Отчёта;
  Каждый объект в массиве — это одна строка;
  Каждый объект содержет поля, ключами которого являются Системные имена полей, а значениями являются данные (например, "status": "Активен").

• metadata — объект, содержащий дополнительные данные об Отчёте, например, выбранные Фильтры;
  Ключами объекта являются Системные имена полей, а значениями сами Данные (например, "metadataFieldName": "Тестовый пользователь").

• hasErrors — булево значение;
  Были ли ошибки при попытке сформировать Отчёт;
  Если значение true, значит Отчёт не сформирован и нужно смотреть ошибки в поле errors.

• errors — объект, содержащий ошибки;
  Ключами являются Системные имена полей, а значениями Текст ошибки.