Dynamic data model API overview (using class 'abc/mnesia' as an example)

Overview

Allows CRUD operations on a dynamic class collection.

Operations are also available via the WebSocket API (capability `rest`).

Attachment file operations are supported.

When a path with a trailing slash is specified, the GET operation returns the list of available child-level sections/collections.

To perform operations on entities of a class with storage_mode: history, the path must include the value of the property configured in the class in opts.partition_property. For example the value from the "dateTime" property when making requests to an entity of the platform/log/HistoryChanges class.

Requests

HTTP verb Endpoint Description

POST

/rest/v1/model/<classname>

Creating a new entity in a dynamic class collection

GET

/rest/v1/model/<classname>

Getting the list of entities from a dynamic class collection

GET

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

Getting entity data from a dynamic class collection

PUT

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

Replacing/placing an entity in a dynamic class collection

PATCH

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

Modifying entity data in a dynamic class collection

DELETE

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

Deleting an entity from a dynamic class collection

GET

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

Getting entity data from a historical dynamic class collection

PUT

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

Replacing/placing an entity in a historical dynamic class collection

PATCH

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

Modifying entity data in a historical dynamic class collection

DELETE

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

Deleting an entity from a historical dynamic class collection

CLEAR

/rest/v1/model/<classname>

Clears the dynamic class collection

LOOKUP

/rest/v1/model/<classname>

Searching for an entity identifier in a dynamic class collection

SETUP

/rest/v1/model/<classname>

Runtime configuration of a dynamic class collection


Creating a new entity in a dynamic class collection

Request

Field description: determined based on class property settings (class entity)

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

determined based on class property settings (class entity)

Response

Field description: determined based on class property settings (class entity)

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

Getting the list of entities from a dynamic class collection

Request

Table 1. Request parameters
Name Type Description

filter

object

Element filter. It is a logical expression in Polish notation. Specified as a JSON array representing the Polish notation of a complex logical expression.

The first element of any array is the function name (string); the second and subsequent list elements are function arguments, each of which can in turn be an expression (JSON array).

Examples:

  • ["==",["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>

Resource sorting order in the list. Applies a sequence of fields, each with a defined sort direction; when values match, applies the next field.

Examples:

  • order=["priority"]

  • order=["priority","name"]

  • order=[{"state":"desc"}]

  • order=[{"priority":"desc"},"name"]

  • order=[["desc",["upper",["property","name"]]]]

  • order=[["asc",["isnull",["property","name"]]],["asc",["upper",["property","name"]]],["asc",["property","somefield1"]]],{"somefield2","asc"},"somefield3"]

mask

array<str>

List of fields to output. Available fields for output: (configured in the specific class options - the `max_mask` field). For dynamic collections, masking is performed only at the first depth level; composite values are included or excluded entirely.

Example:

  • mask=["id","name"]

offset

int

Offset in the list of resources to output. Zero-based index in the filtered (filter) and sorted (order) resource list from which output should start. Usually used together with the limit parameter for paginated output.

Example:

  • offset=2

limit

int

Maximum number of resources to output from the filtered (filter), sorted (order), and offset (offset) resource list. Usually used together with the offset parameter for paginated output. If limit=0, returns information about the number of found elements without applying the offset parameter.

Example:

  • limit=2

countonly

bool

Flag indicating whether to output only the number of elements matching the filter conditions.

snapshot

any

Streaming read operation identifier for optimizing paginated reading from collections of types runtime, ram, and ets.

Without the 'snapshot' parameter, each read request for each page filters the entire table and sorts the result, from which the page is then cut.

If the task is to load data into the cache by reading many pages, snapshot should be used. This can optimize the process. There are two different approaches.

A) Paginated reading from a snapshot

Applied if the 'snapshot' parameter is set and differs from true. Based on the combination of 'snapshot' + 'filter' + 'order' values, the system creates a temporary snapshot of object identifiers sorted and matching the filter conditions. The snapshot is deleted automatically 10 seconds after the last request.

The process looks as follows:

  1. The required filter (filter) and sorting (order) are formed.

  2. A subscription to collection change notifications with this filter is made. Incoming notifications accumulate.

  3. A unique identifier is generated for the streaming read operation (snapshot).

  4. A record count request with this filter and sorting is made using the countonly parameter.

  5. Multiple paginated reads are performed using the offset and limit options and the same filter and sorting. Completion criterion is offset+limit reaching the record count returned in the previous step.

  6. Notifications received during paginated streaming reads are applied in strict arrival order.

  7. At this point the cache is fully loaded. Then the subscription is regularly renewed, and incoming change notifications are applied and modify the cache.

The mode is not applied to collections with fewer than 3000 records or to aggregating requests.

B) Reading the snapshot entirely

Applied if the 'snapshot' parameter equals true. If cache loading does not require sorting, this mode is more optimal.

Without the order parameter the request executes significantly more optimally in time and server memory usage. The limit and offset options are not prohibited and will apply if specified, but the cache loading process does not assume their use.

The process looks as follows:

  1. The required filter (filter) is formed.

  2. A subscription to collection change notifications with this filter is made. Incoming notifications accumulate.

  3. Reading is performed with the same filter (filter), without sorting (order), without pagination (limit, offset).

  4. If the read request is made via a WebSocket connection, the response returns 'download_url' instead of content (valid for 60 seconds). To get the data, immediately access the same web server at this path and download a JSON document with full collection data matching the passed filter conditions. If the selection read request was made via HTTP REST API, the entire data volume is returned immediately. It makes sense to tell the server about readiness to use gzip.

  5. Notifications received during paginated streaming reads are applied in strict arrival order.

  6. At this point the cache is fully loaded. Then the subscription is regularly renewed, and incoming change notifications are applied and modify the cache.

interval

[Date1,Date2]

For collections of type 'history' and 'transactionlog', a required parameter specifying the time interval for data selection. To access the endpoint of a specific element of such collections, use the date as an intermediate path segment.

aggr

object

Aggregated value descriptor. The key is an arbitrary field name, the value is an aggregating expression (where the main function is aggregating). Used together with the 'groupby' parameter.

Example:

  • {"cnt": ["count","*"], "total": ["sum",["ddiv",["property","cost"],1000]]}

groupby

object

Descriptor of grouping fields or expressions. The key is an arbitrary field name, the value is the name of an actually existing class field or an expression similar to filter, but not necessarily logical. Used together with the 'aggr' parameter.

Example:

  • {"status": "status", "date": ["toYYYYMMDD",["property","dateTime"]]}

Table 2. Functions for building expressions
Function (and synonyms) Number of arguments Description

property

any

Access to any entity field, including by a deep path in complex object and list fields.

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. Aggregation functions
Function (and synonyms) Number of arguments Description

count

1

sum

1

min

1

max

1

avg

1

and

1

or

1

join

2

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

Response

Field description: determined based on class property settings (class entity)

Example response
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"
  }
]

Getting entity data from a dynamic class collection

Request

Table 4. Request parameters
Name Type Description

mask

str

List of fields to output.

flat

bool

Conversion of composite fields to flat form.

Example request
GET /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58 HTTP/1.1
Example request for a historical collection
GET /rest/v1/model/abc/mnesia/2026-03-06T10:14:37.251Z/6f7d27df-017b-ab81-77e7-7cd30a921f58 HTTP/1.1

Response

Field description: determined based on class property settings (class entity)

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

Replacing/placing an entity in a dynamic class collection

The operation performs either a complete entity replacement in the collection if an entity with the specified identifier already exists there, or initial placement with the specified identifier if no entity with such identifier is found in the collection. By default the operation performs a preliminary read to check security conditions set in the class. The preliminary read can be disabled by class settings.

  • Entities with storage type 'runtime' and a configured automatic deletion mode can extend their lifetime on replacement.

Request

Field description: determined based on class property settings (class entity)

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

determined based on class property settings (class entity)
Example request for a historical collection
PUT /rest/v1/model/abc/mnesia/2026-03-06T10:14:37.251Z/6f7d27df-017b-ab81-77e7-7cd30a921f58 HTTP/1.1
Content-Type: application/json; charset=utf-8

determined based on class property settings (class entity)

Response

Field description: determined based on class property settings (class entity)

Example response
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": "i1",
  "pint": 8640000,
  "plong": 1630924980256,
  "pstr": "Next value"
}

Modifying entity data in a dynamic class collection

The operation performs a preliminary read and then merges the current object with the passed value.

  • The value 'null' zeroes the field.

  • Values of fields with type 'any' are merged in depth instead of replaced, by the number of levels specified in the corresponding field options.

  • Values of all fields having the 'multi' option (arrays) can be appended to the end of current values if the 'append' parameter is passed in the request (append=true).

  • Entities with storage type 'runtime' and a configured automatic deletion mode can extend their lifetime on update.

Fields prohibited from modification: id

Request

Field description: determined based on class property settings (class entity)

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

determined based on class property settings (class entity)
Example request for a historical collection
PATCH /rest/v1/model/abc/mnesia/2026-03-06T10:14:37.251Z/6f7d27df-017b-ab81-77e7-7cd30a921f58 HTTP/1.1
Content-Type: application/json; charset=utf-8

determined based on class property settings (class entity)

Response

Field description: determined based on class property settings (class entity)

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

Deleting an entity from a dynamic class collection

Request

Example request
DELETE /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58 HTTP/1.1
Example request for a historical collection
DELETE /rest/v1/model/abc/mnesia/2026-03-06T10:14:37.251Z/6f7d27df-017b-ab81-77e7-7cd30a921f58 HTTP/1.1

Response

Example response
HTTP/1.1 204 No Content

Clears the dynamic class collection

Request

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

Response

Example response
HTTP/1.1 204 No Content

Searching for an entity identifier in a dynamic class collection

Searches for a resource by the specified key and returns identifier(s) for building the endpoint.

Key fields for search: (identifier and fields configured in the specific class options - the `lookup_properties` field)

Request

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

"asdfasdfasdf"

Response

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

[
  "6f7d27df-017b-ab81-77e7-7cd30a921f58"
]
Example unsuccessful response
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

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

Runtime configuration of a dynamic class collection

Performs runtime configuration of the collection, changing its behavior.

Request format
{
   "cmd": ...,
   ...
}

Command types ('cmd'):

  • suspend_notification - temporarily suspends sending notifications about class entity changes (effective until cancellation or microservice restart). This mode can be used for large-scale modification operations with hundreds or thousands of subscribers.

  • resume_notification - resumes previously suspended notification sending. At the same time it may send (by default) or not send the 'reload' operation event to all current subscribers (additional optional 'send_reload' parameter).

  • read_partitions - returns the partition list. Applies to types 'history' and 'transactionlog' with clickhouse storage.

  • drop_partition - deletes the specified partition passed in the additional 'partition' parameter with a value taken from the 'read_partitions' request response. Applies to storage_mode 'history' and 'transactionlog' with clickhouse storage.

  • optimize - performs table finalization/optimization. Applies to storage_mode 'transactionlog' with clickhouse storage.

  • reencrypt_secrets - re-encrypts secret properties of class entities with the current installation key (more). Admin role only. On a DMS node one class is re-encrypted at a time; the rest wait in the queue. Returns state: status running or queued with position (queue place, starting at 1). If the class is already being re-encrypted or is queued — error 409. A repeated command after completion starts re-encryption again. Not applicable to classes without secret properties, to storage_mode 'history', 'transactionlog', 'ets', 'ram', 'runtime', and without an installation key (422).

  • reencrypt_secrets_state - returns class re-encryption state without starting it. Admin role only. status: none (not started), queued (with position), running, done, failed, cancelled; kid (installation key), done (entities viewed), changed (re-encrypted), errors (not re-encrypted: value cannot be decrypted), started; after completion — finished, for done — marked (class marked as re-encrypted: no errors). State is stored on the DMS node and is lost on its restart.

  • reencrypt_secrets_cancel - cancels class re-encryption. Admin role only. A queued class is removed from the queue; an ongoing re-encryption stops after the current entity portion; status cancelled, the class is not marked as re-encrypted. If the class is not queued and not being re-encrypted (or is already completing re-encryption) — error 409.

  • reencrypt_secrets_mark - marks the class as re-encrypted with the current key without re-encryption (data is known to be current, for example the class was recreated with the same data). Admin role only. if_empty parameter: true — only if the class has no entities. Response marked: true | false. Refusals are as for reencrypt_secrets; class queued or being re-encrypted — error 409.

Request

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

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

Response

Example successful response
HTTP/1.1 202 No Content
Example unsuccessful response
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

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