Обзор API динамической модели данных (на примере класса 'abc/mnesia')

Содержание

Обзор
Запросы
Содержание (дочерние ресурсы)
Ссылки

Обзор

Позволяет производить CRUD операции с коллекцией динамического класса.

Также доступно проведение операций через Websocket-API (capability `rest`).

Поддерживаются операции с файлами вложений.

При указании пути со слэшем на конце, операция GET выдает список доступных разделов/коллекций дочернего уровня.

Запросы

HTTP verb Endpoint Описание

HTTP verb	Endpoint	Описание
`POST`	`/rest/v1/model/<classname>`	Создание новой сущности в коллекции динамического класса
`GET`	`/rest/v1/model/<classname>`	Получение списка сущностей из коллекции динамического класса
`GET`	`/rest/v1/model/<classname>/<id>`	Получение данных сущности из коллекции динамического класса
`PATCH`	`/rest/v1/model/<classname>/<id>`	Изменение данных сущности из коллекции динамического класса
`DELETE`	`/rest/v1/model/<classname>/<id>`	Удаление сущности из коллекции динамического класса
`CLEAR`	`/rest/v1/model/<classname>`	Очищает коллекцию динамического класса
`LOOKUP`	`/rest/v1/model/<classname>`	Поиск идентификатора сущности в коллекции динамического класса

POST

/rest/v1/model/<classname>

Создание новой сущности в коллекции динамического класса

GET

/rest/v1/model/<classname>

Получение списка сущностей из коллекции динамического класса

GET

/rest/v1/model/<classname>/<id>

Получение данных сущности из коллекции динамического класса

PATCH

/rest/v1/model/<classname>/<id>

Изменение данных сущности из коллекции динамического класса

DELETE

/rest/v1/model/<classname>/<id>

Удаление сущности из коллекции динамического класса

CLEAR

/rest/v1/model/<classname>

Очищает коллекцию динамического класса

LOOKUP

/rest/v1/model/<classname>

Поиск идентификатора сущности в коллекции динамического класса

Создание новой сущности в коллекции динамического класса

Запрос

Описание полей: определяются на основании настроек свойств класса (class entity)

Пример запроса

POST /rest/v1/model/abc/mnesia HTTP/1.1
Content-Type: application/json; charset=utf-8

определяются на основании настроек свойств класса (class entity)

Ответ

Описание полей: определяются на основании настроек свойств класса (class entity)

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "6f7d27df-017b-ab81-77e7-7cd30a921f58",
  "patts":[],
  "pbool": false,
  "penum": "i1",
  "pint": 8640000,
  "plong": 1630924984167,
  "pstr": "asdfasdfasdf"
}

Получение списка сущностей из коллекции динамического класса

Запрос

Table 1. Параметры запроса
Имя	Тип	Описание
`filter`	`object`	Фильтр элементов. Представляет собой логическое выражение в польской нотации. Задается в виде json-массива, представляющего собой польскую нотацию сложного логического выражения. Первый элемент любого массива - название функции (строка), второй и последующий элементы списка - аргументы функции, каждый из которых в свою очередь может быть выражением (json-массивом). Примеры: `["==",["property","status"],"initial"]` `["and",["in",["property","status"],["list",initial","active"]]` Список доступных функций.
`order`	`array<object\|str>`	Порядок сортировки ресурсов в списке. Применяет последовательность полей, где по каждому определено направление сортировки, при совпадении значений применяет следующее поле. Примеры: `order=[{"state":"desc"}]` `order=[{"priority":"desc"},{"name":"asc"}]` `order=["priority","name"]`
`mask`	`array<str>`	Список полей для вывода. Доступные поля для выдачи: (настраивается в опциях конкретного класса - поле `max_mask`). Допускается указывать композитные поля как целиком, так и с указанием интересующих вложенных опций через точку вне зависимости от значения параметра flat. Пример: `mask=["id","name"]`
`offset`	`int`	Смещение в списке ресурсов, подлежащих выдаче. Порядковый номер с нуля в отфильтрованном (`filter`) и отсортированном списке ресурсов (`order`), начиная с которого следует производить выдачу. Обычно используется совместно с параметром `limit` для постраничного вывода. Пример: `offset=2`
`limit`	`int`	Максимальное количество ресурсов, подлежащее выдаче из отфильтрованного (`filter`), отсортированного (`order`) и смещенного (`offset`) списка ресурсов. Обычно используется совместно с параметром `offset` для постраничного вывода. Если `limit=0`, то возвращает информацию о количестве обнаруженных элементов без применения параметра `offset`. Пример: `limit=2`
`countonly`	`bool`	Флаг-указатель необходимости выдачи лишь количества элементов, попадающих под условия фильтра.
`interval`	`[Date1,Date2]`	Для коллекций типа 'history' и 'transactionlog' обязательный параметр, указывающий временной интервал для выборки данных. При этом для обращения к эндпойнту конкретного элемента таких коллекций необходимо использовать дату как промежуточный отрезок пути.
`aggr`	`object`	Дескриптор агрегирующих значений. Ключ - произвольное название поля, значение - агрегирующие выражение (где основная функция - агрегирующая). Используется совместно с параметром 'groupby'. Пример: `{"cnt": ["count","*"], "total": ["sum",["ddiv",["property","cost"],1000]]}`
`groupby`	`object`	Дескриптор группирующих полей или выражений. Ключ - произвольное название поля, значение - название реально существующего поля класса, либо выражение, аналогичное фильтру, однако не обязательно логическое. Используется совместно с параметром 'aggr'. Пример: `{"status": "status", "date": ["toYYYYMMDD",["property","dateTime"]]}`

Table 2. Функции для построения выражений
Функция (и синонимы)	Количество аргументов	Описание
`property`	`any`	Доступ к любому полю сущности, в том числе по глубокому пути в сложных объектных и списочных полях.
`isnull`	`1`
`isnotnull`	`1`
`not, !`	`1`
`bool`	`1`
`integer`	`1`
`float`	`1`
`string`	`1`
`uuid`	`1`
`const`	`1`
`lower`	`1`
`upper`	`1`
`year, toYYYY, toYear`	`1`
`quarter`	`1`
`month`	`1`
`day`	`1`
`hour`	`1`
`minute`	`1`
`second`	`1`
`weekday`	`1`
`toYYYYMM`	`1`
`toYYYYMMDD`	`1`
`concat, .`	`any`
`join, ..`	`any`
`list`	`any`
`null`	`0`
`now`	`0`
`+, add`	`any`
`-, sub`	`2`
`*, mul`	`2`
`/, div`	`2`
`//, ddiv`	`2`
`%, rem`	`2`
`&&, and`	`any`
`\|\|, or`	`any`
`==, equal, equals`	`2`
`!=, <>, notequal, notequals`	`2`
`>, greater`	`2`
`>=, notless, greaterorequal`	`2`
`<, less`	`2`
`⇐, =<, notgreater, lessorequal`	`2`
`in`	`2`
`inlist`	`2`
`contains`	`2`
`like`	`2`
`interval_in_minutes`	`2`
`dateadd`	`2`
`datediff`	`2`
`between`	`3`

Table 3. Агрегирующие функции
Функция (и синонимы)	Количество аргументов	Описание
`count`	`1`
`sum`	`1`
`min`	`1`
`max`	`1`
`avg`	`1`
`and`	`1`
`or`	`1`
`join`	`2`

Пример запроса

GET /rest/v1/model/abc/mnesia?offset=0&limit=2 HTTP/1.1

Ответ

Описание полей: определяются на основании настроек свойств класса (class entity)

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "id": "6f7d27df-017b-ab81-77e7-7cd30a921f58",
    "patt":{
      "hasha": "md5;A95C530A7AF5F492A74499E70578D150",
      "link": "fs://1a2325b6-017b-abab-bba4-7cd30a921f58/fstest_attaches/test.rootdomain.ru/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patt/content",
      "mtime": "2021-09-07T10:47:06Z",
      "name": "content",
      "size": 12
    },
    "patts":[
      {
        "hasha": "md5;2B00042F7481C7B056C4B410D28F33CF",
        "link": "fs://1a2325b6-017b-abab-bba4-7cd30a921f58/fstest_attaches/test.rootdomain.ru/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts/app.mp3",
        "mtime": "2021-09-07T10:47:47Z",
        "name": "app.mp3",
        "size": 538925
      },
      {
        "hasha": "md5;236C8E5A21AF6E369045F004B1CAEA1C",
        "link": "fs://1a2325b6-017b-abab-bba4-7cd30a921f58/fstest_attaches/test.rootdomain.ru/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts/test.json",
        "mtime": "2021-09-07T10:47:47Z",
        "name": "test.json",
        "size": 14
      }
    ],
    "pbool": false,
    "penum": "i1",
    "pint": 8640000,
    "plong": 1630924984167,
    "pstr": "asdfasdfasdf"
  }
]

Получение данных сущности из коллекции динамического класса

Запрос

Table 4. Параметры запроса
Имя	Тип	Описание
`mask`	`str`	Список полей для вывода.
`flat`	`bool`	Преобразование в плоский вид составных полей.

Пример запроса

GET /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58 HTTP/1.1

Ответ

Описание полей: определяются на основании настроек свойств класса (class entity)

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "6f7d27df-017b-ab81-77e7-7cd30a921f58",
  "patt":{
    "hasha": "md5;A95C530A7AF5F492A74499E70578D150",
    "link": "fs://1a2325b6-017b-abab-bba4-7cd30a921f58/fstest_attaches/test.rootdomain.ru/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patt/content",
    "mtime": "2021-09-07T10:47:06Z",
    "name": "content",
    "size": 12
  },
  "patts":[
    {
      "hasha": "md5;2B00042F7481C7B056C4B410D28F33CF",
      "link": "fs://1a2325b6-017b-abab-bba4-7cd30a921f58/fstest_attaches/test.rootdomain.ru/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts/app.mp3",
      "mtime": "2021-09-07T10:47:47Z",
      "name": "app.mp3",
      "size": 538925
    },
    {
      "hasha": "md5;236C8E5A21AF6E369045F004B1CAEA1C",
      "link": "fs://1a2325b6-017b-abab-bba4-7cd30a921f58/fstest_attaches/test.rootdomain.ru/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts/test.json",
      "mtime": "2021-09-07T10:47:47Z",
      "name": "test.json",
      "size": 14
    }
  ],
  "pbool": false,
  "penum": "i1",
  "pint": 8640000,
  "plong": 1630924984167,
  "pstr": "asdfasdfasdf"
}

Изменение данных сущности из коллекции динамического класса

Операция проводит предварительное чтение, и затем слияние текущего объекта с переданным значением.

Значение 'null' обнуляет поле.
Значения полей с типом 'any' вместо замещения смешиваются в глубину на количество уровней, указанное в опциях соответствующего поля.
Значения всех полей, имеющих опцию 'multi' (массивы), могут добавляться в конец текущих значений, если в запросе передан параметр 'append' (append=true).
Сущности с типом хранения 'runtime' и настроенным режимом автоматического удаления могут продлять время жизни при обновлении.

Поля запрещенные для изменения: id

Запрос

Описание полей: определяются на основании настроек свойств класса (class entity)

Пример запроса

PATCH /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58 HTTP/1.1
Content-Type: application/json; charset=utf-8

определяются на основании настроек свойств класса (class entity)

Ответ

Описание полей: определяются на основании настроек свойств класса (class entity)

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "6f7d27df-017b-ab81-77e7-7cd30a921f58",
  "patt":{
    "hasha": "md5;A95C530A7AF5F492A74499E70578D150",
    "link": "fs://1a2325b6-017b-abab-bba4-7cd30a921f58/fstest_attaches/test.rootdomain.ru/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patt/content",
    "mtime": "2021-09-07T10:47:06Z",
    "name": "content",
    "size": 12
  },
  "patts":[
    {
      "hasha": "md5;2B00042F7481C7B056C4B410D28F33CF",
      "link": "fs://1a2325b6-017b-abab-bba4-7cd30a921f58/fstest_attaches/test.rootdomain.ru/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts/app.mp3",
      "mtime": "2021-09-07T10:47:47Z",
      "name": "app.mp3",
      "size": 538925
    },
    {
      "hasha": "md5;236C8E5A21AF6E369045F004B1CAEA1C",
      "link": "fs://1a2325b6-017b-abab-bba4-7cd30a921f58/fstest_attaches/test.rootdomain.ru/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58/patts/test.json",
      "mtime": "2021-09-07T10:47:47Z",
      "name": "test.json",
      "size": 14
    }
  ],
  "pbool": true,
  "penum": "i2",
  "pint": 8640000,
  "plong": 1630924984167,
  "pstr": "Other value"
}

Удаление сущности из коллекции динамического класса

Запрос

Пример запроса

DELETE /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58 HTTP/1.1

Ответ

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

HTTP/1.1 204 No Content

Очищает коллекцию динамического класса

Запрос

Пример запроса

CLEAR /rest/v1/model/abc/mnesia HTTP/1.1

Ответ

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

HTTP/1.1 204 No Content

Поиск идентификатора сущности в коллекции динамического класса

Производит поиск ресурса по указанному ключу, возвращает идентификатор(ы) для построения endpoint.

Ключевые поля для поиска: (идентификатор и поля, настроенные в опциях конкретного класса - поле `lookup_properties`)

Запрос

Пример запроса

LOOKUP /rest/v1/model/<classname> HTTP/1.1
Content-Type: application/json; charset=utf-8

"asdfasdfasdf"

Ответ

Пример успешного ответа

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

[
  "6f7d27df-017b-ab81-77e7-7cd30a921f58"
]

Пример неуспешного ответа

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error_code": 1404,
  "error_message": "Lookup failed"
}

Содержание (дочерние ресурсы)

Ссылки

Websocket API для CRUD операций через канал интеграции
Websocket API для CRUD операций через подключение с авторизацией пользователя
Функции общего назначения для фильтра и базы агрегации
Функции агрегации