Dynamic data model API overview (on the example of class 'abc/mnesia')

Overview

Allows you to perform CRUD operations on a collection of a dynamic class.

Transactions are also available via Websocket-API (capability `rest`).

Operations with attachment files are supported.

If you specify a path with a slash at the end, the GET operation produces a list of available child-level partitions/collections.

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 a list of entities from a dynamic class collection

GET

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

Retrieving entity data from a dynamic class collection

PATCH

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

Modifying entity data from a dynamic class collection

DELETE

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

Deleting an entity from a dynamic class collection

CLEAR

/rest/v1/model/<classname>

Clears the collection of a dynamic class

LOOKUP

/rest/v1/model/<classname>

Searching for an entity identifier in a dynamic class collection

SETUP

/rest/v1/model/<classname>

Rantime customization of a dynamic class collection collection

Creating a new entity in a dynamic class collection

Request

Field Description: are determined based on the class property settings (class entity)

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

are determined based on the class property settings (class entity)

Response

Field Description: are determined based on the class property settings (class entity)

Response example
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 a list of entities from a dynamic class collection

Request

Table 1. Request parameters
Name Type Description

filter

object

Element Filter. Represents a logical expression in Polish notation. Defined as a json array representing the Polish notation of a complex logical expression.

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

Examples:

  • ["==",["property","status"],"initial"]

  • ["and",["in",["property","status"],["list",initial","active"]]

List of available functions.

order

array<object|str>

The sort order of the resources in the list. Applies a sequence of fields, where each field has a sort direction defined, and applies the next field when values match.

Examples:

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

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

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

mask

array<str>

List of fields to output. Available fields for output: (is configured in the options of a particular class - field `max_mask`). It is allowed to specify composite fields either as a whole or with the nested options of interest indicated by a dot, regardless of the value of the parameter flat.

Example:

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

offset

int

Offset in the list of resources to be issued. The sequence number from zero in the filtered (filter) and sorted list of resources (order) from which to output. Usually used in conjunction with the limit parameter for paginated output.

Example:

  • offset=2

limit

int

The maximum number of resources to be output from a filtered (filter), sorted (order) and offset (offset) list of resources. Typically used in conjunction with the offset parameter for paginated output. If limit=0, it returns information about the number of detected items without applying the parameter offset.

Example:

  • limit=2

countonly

bool

Flag indicating the necessity to output only the number of items that fall under the filter conditions.

interval

[Date1,Date2]

For collections like 'history' and 'transactionlog', a mandatory parameter specifying the time interval for data sampling. In this case, to refer to the endpoint of a particular element of such collections, it is necessary to use the date as an intermediate path segment.

aggr

object

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

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 a real class field, or an expression similar to filter, but not necessarily boolean. Used in conjunction with the parameter 'aggr'.

Example:

  • {"status": "status", "date": ["toYYYYMMDD",["property","dateTime"]]}
Table 2. Functions for constructing expressions
Function (and synonyms) Number of arguments Description

property

any

Access any entity field, including the 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. Aggregating functions
Function (and synonyms) Number of arguments Description

count

1

sum

1

min

1

max

1

avg

1

and

1

or

1

join

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

Response

Field Description: are determined based on the class property settings (class entity)

Response example
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"
  }
]

Retrieving entity data from a dynamic class collection

Request

Table 4. Request parameters
Name Type Description

mask

str

A list of fields to output.

flat

bool

Conversion to flat form of composite fields.
Request example
GET /rest/v1/model/abc/mnesia/6f7d27df-017b-ab81-77e7-7cd30a921f58 HTTP/1.1

Response

Field Description: are determined based on the class property settings (class entity)

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

Modifying entity data from a dynamic class collection

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

  • A value of 'null' will reset the field to zero.

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

  • The values of all fields that have the 'multi' option (arrays) can be added to the end of the current values if the parameter is passed in the query 'append' (append=true).

  • Entities with a 'runtime' storage type and a configured auto-delete mode can extend their lifetime on refresh.

Fields prohibited for modification: id

Request

Field Description: are determined based on the class property settings (class entity)

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

are determined based on the class property settings (class entity)

Response

Field Description: are determined based on the class property settings (class entity)

Response example
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

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

Response

Response example
HTTP/1.1 204 No Content

Clears the collection of a dynamic class

Request

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

Response

Response example
HTTP/1.1 204 No Content

Searching for an entity identifier in a dynamic class collection

Searches the resource for the specified key, returns the identifier(s) to build the endpoint.

Key fields to search for: (identifier and fields configured in the options of a particular class - field `lookup_properties`)

Request

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

"asdfasdfasdf"

Response

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

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

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

Rantime customization of a dynamic class collection collection

Performs rantime tuning of the collection by changing the behavior.

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

Types of commands ('cmd'):

  • suspend_notification - temporarily suspends sending notifications about class entities modifications (valid until the microservice is canceled or restarted). This mode can be used for large-scale modification operations with hundreds or thousands of subscribers.

  • resume_notification - resumes previously suspended notification sending. Simultaneously can send (by default) or not send a 'reload' operation event to all current subscribers (optional additional parameter) 'send_reload').

Request

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

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

Response

Example of a successful response
HTTP/1.1 202 No Content
Example of an 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"
}

Table of Contents (subsidiary resources)

References