.. _api:

API Платформы Пересвет
======================

Правила API
-----------

.. warning:: Внимание!
   При создании любых сущностей (тэги, объекты, тревоги и т.д.) в их именах
   допустимы любые символы. При этом обратный слэш (\\) и кавычки должны предваряться символом обратного слэша.

Есть несколько базовых правил, на которых основывается API платформы:

#. Имена атрибутов в json-объектах, названия запросов придерживаются
   правил camelCase.

   Пример:

   .. code-block:: json

      {
         "parentId": "...",
         "tagName": "..."
      }

#. Тело запроса к платформе содержит только один json-объект.
   Массивы данных передаются внутри этого объекта.
#. Ответ на запрос также содержит только один json-объект.
#. В случае ошибки обработки запроса в json-объекте ответа 
   на запрос есть ключ ``detail```, значение
   которого - список пояснений к ошибке:

   .. code-block:: json

      {
        "detail": [
            {
                  "type": "type_of_error",
                  "loc": [
                     "place_of_error"
                  ],
                  "msg": "message",
                  "input": {},
                  "ctx": {
                     "error": "name_of_error"
                  }
            }
         ]
      }

   либо строка:

   .. code-block:: json

      {
        "detail": "описание ошибки"
      }

#. По возможности все команды платформы работают с массивами данных.
   См. документацию на каждую команду.

#. В связи с использованием ldap-сервера для хранения иерархий
   имена всех сущностей представлены в виде атрибута ``cn``.

#. У каждого узла в иерархии присутствует атрибут ``entryUUID``.
   Это специальный неизменяемый атрибут, содержащий уникальный идентификатор узла.
   Платформа сама присваивает значение этому атрибуту при создании нового узла.
   При перемещении узла по иерархии этот атрибут сохраняется без изменений.

Модули
------

.. toctree::
   :maxdepth: 6

   Тревоги<alerts>
   Теги<tags>
   Обьекты<objects>
   Коннекторы<connectors>
   Хранилища данных<dataStorages_api_doc>
   Расписания<schedules>
   Методы<methods_api_doc>
   Запись/получение данных<data_api>