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

Обзор

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

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

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

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

Запросы

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>

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

SETUP

/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"]]

  • `["equals",["integer",["property","rawMessage","attachments",0,"sticker","images",0,"height"]],64]

Список доступных функций.

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"
}

Рантайм-настройка коллекции коллекции динамического класса

Производит рантайм-настройку коллекции, изменяя поведение.

Формат запроса
{
   "cmd": ...,
   ...
}

Виды команд ('cmd'):

  • suspend_notification - временно приостанавливает отправку уведомлений об изменении сущностей класса (действует до отмены или перезагрузки микросервиса). Этот режим может применяться при масштабных операциях модификации при сотнях и тысячах подписчиков.

  • resume_notification - возобновляет ранее приостановленную отправку уведомлений. Одновременно может отправлять (по умолчанию) или не отправлять всем актуальным подписчикам событие об операции 'reload' (дополнительный опциональный параметр 'send_reload').

Запрос

Пример запроса
SETUP /rest/v1/model/<classname> HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "cmd": "resume_notification",
  "send_reload": false
}

Ответ

Пример успешного ответа
HTTP/1.1 202 No Content
Пример неуспешного ответа
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error_code": 1506,
  "error_message": "Invalid content. Expected 'cmd'::string"
}

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

Ссылки

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт