Обзор API

Endpoints

Endpoint – это URL на веб-сервере системы «Era», по которому адресуется какой-либо ресурс и однозначно ему соответствует. Вся совокупность endpoint в REST API образует дерево.

Каждый endpoint с необходимостью располагается ровно в одном разделе.

Категории ресурсов и порядок доступа

Ресурсы предоставляемые системой через веб-сервер делятся на публичные и закрытые. В частности к публичным относятся все статические файлы (каталог www), поставляемые с дистрибутивом. В каждом домене через API /rest/v1/fs/targets/www можно добавлять дополнительные публичные ресурсы, доступные всем по url /public/<DOMAIN>/…​. Публичными являются некоторые виды метаданных, иконки, логотипы и дефолтные значения для веб-приложений. Отдельные виды ресурсов, доступных через API, могут быть добавлены в раздел публичных путем создания ролей и предоставления им доступа к соответствующим Endpoint с указанием разрешенных операций.

Ресурсы, доступные для всех авторизованных пользователей. К таким ресурсам относятся Endpoint предоставляющие информацию о подключении, о самом пользователе и его ролях. К таким ресурсам относятся в частности статические файлы ролевых приложений, загруженных в домен. Аналогично в эту категорию могут быть добавлены некоторые ресурсы путем создания ролей и предоставления им доступа к соответствующим Endpoint с указанием разрешенных операций.

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

Для пользования API следует авторизоваться. В ответ на запрос авторизации сервер создает сессию и проставляет cookie с ограниченным сроком жизни. Периодически при обращении к веб-серверу время жизни сессии продляется, и также обновляется время жизни cookie. Запросы в рамках веб-сокета, авторизованного под той же сессией, также продлевают ее время жизни, но однако не затрагивают время жизни cookie. Количество одновременно существующих сессий, созданных одним пользователем, ограничивается по умолчанию 10 штуками, и может быть изменено в свойствах пользователя. При нехватке сессий производится отказ, но предварительно делается попытка очистить "висящие" сессии, которые при активных приложениях должны были бы быть продлены, но слишком давно не обновлялись.

Запросы /api без сессии могут передавать учетные данные в параметрах запроса domain, login, pwd; сессия при этом не создается. Параметр td — устаревший синоним domain: если переданы оба, доменом входа считается td, а domain остается параметром команды.

Разделы REST API

Структура разделов приведена в последовательности, соответствующей приоритету размещения в них ресурсов. Если какой-либо ресурс по совокупности своих характеристик может быть соотнесен с несколькими разделами, то он размещается в более приоритетном.

Другие endpoint