'rest' capability for WebSocket User API

Table of Contents

Overview

Overview

Provides an interface to perform CRUD operations on entities of static and dynamic classes. To work requires a user role that allows access to the /ws#rest route with method WEBSOCKET.

On requests, performs additional role-based authorization to access specific REST-API endpoints for a specific operation. Differentiate between collection endpoints, specific collection elements, and properties for accessing attachments. For example, if a user routes in roles only the GET method to a class collection, they will be able to read the collection, but will not be able to read a specific entity or modify and create entities.

Each non-empty change is finalized by generating notifications to subscribers.

No rest-capability events are generated.

Among the classes that can be accessed:

Domain Center Static Collections;
Dynamic data model collections;
Special Collections.

Query construction

General view of the request:

[
  "rest",
  {
    "qid":"16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "...",
    "classpath": "/rest/v1/...",
    ...
  }
]

Required fields of the request:

operation - class operation type (read, create, replace, update, delete, clear, lookup).
classpath - the full path to the class collection in REST-API: "/rest/v1/model/builder/packages/Packages",

Specific query fields:

interval - list of two dates (beginning and end of the period). It is necessary to specify in operations of selection from collections of dynamic classes having storage_mode = history or transactionlog.
id - identifier of a specific entity. When performing operations with a collection (selecting items, searching, clearing the collection), it is necessary to exclude the field from the query.
content - query content. It is necessary when creating, replacing, modifying an entity (json-object), as well as in case of key search (value to be searched - string or number).

The sample condition fields are all optional:

filter - filter condition. See general-purpose functions.
order - sort order.
mask - rendition fields.
offset - sampling bias.
limit - limiting the number of elements in the sample.
aggr - aggregation fields. An object containing return fields as keys and aggregation functions as values. Allows a superposition of functions as an argument, the construction of which is similar to filter functions. See (aggregation functions).
groupby - aggregation base. An object containing the returned fields as keys and the object field names as values, or a list that is a superposition of functions. The construction of functions is similar to filter functions. See (general-purpose functions).

Supported operations are:

read - sampling from the collection, including aggregation.
read - if the id field is specified, the data of a specific entity with the specified identifier is returned in response to the request. Optional masking is allowed (mask).
lookup - search for collection item identifiers by key fields. The value for the search is passed to the content.
clear - collection cleanup. Supported only in dynamic class collections.
create - Creating an entity in a collection with autogenerated identifier.
replace - creation or complete replacement of an entity with the specified identifier. Supported only in dynamic class collections.
update - modify an existing entity with the specified identifier. Unspecified fields remain unchanged. In dynamic class collections (dms), entire field values are replaced. In static class collections (dc), composite fields allow partial updates 1 level deep.
delete - deleting an existing entity with the specified identifier.
setup - rantime customization of the collection (for example, temporary suspension of sending notifications to subscribers about changes). The type of operation and its possible parameters are passed as an object in the field content.

Examples of queries for static and dynamic collections

Selecting items from the collection:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "read",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "filter": ["or",["like",["property","pstr"],"asdf*"],["==",["property","pint"],8640000]],
    "order": ["pstr",{"pint","desc"},{"id","asc"}],
    "mask": ["id","pstr"],
    "offset": 0,
    "limit": 2
  }
]

Aggregate sampling from the collection:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "read",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "filter": ["like",["property","pstr"],"a*"],
    "groupby":{"a":["%",["property","pint"],10]},
    "aggr":{"cnt":["sum",["-",["property","pint"],1]]}
    "offset": 0,
    "limit": 2
  }
]

Search for items in a collection by key fields:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "lookup",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "content": "abc"
  }
]

Collection Cleanup:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "clear",
    "classpath": "/rest/v1/model/builder/packages/Packages"
  }
]

Reading Essence:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "read",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "id": "c87a8ca6-0f08-91b7-9d19-2fa86f019916"
  }
]

Creating an entity:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "create",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "content": { ... }
  }
]

Substitute Entity:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "replace",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "id": "c87a8ca6-0f08-91b7-9d19-2fa86f019916",
    "content": { ... }
  }
]

Change of Essence:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "update",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "id": "c87a8ca6-0f08-91b7-9d19-2fa86f019916",
    "content": { ... }
  }
]

Entity Deletion:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "delete",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "id": "c87a8ca6-0f08-91b7-9d19-2fa86f019916"
  }
]

Search for an entity by key:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "lookup",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "content": "asdfasdf"
  }
]

Rantime collection customization:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
    "operation": "setup",
    "classpath": "/rest/v1/model/builder/packages/Packages",
    "content": {
      "cmd": "suspend_notification"
    }
  }
]

Special Collections

/rest/v1/domain/nservices

Executing queries to product layer nanoservices.

Getting a list of active nanoservices:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda0915f7",
    "operation": "read",
    "classpath": "/rest/v1/domain/nservices"
  }
]

Response:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda0915f7",
    "data": [
      {"name":"builder.DataService"},
      {"name":"builder.GeneratorService"}
    ]
  }
]

Executing a request to a nanoservice:

[
  "rest",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09472e",
    "operation": "create",
    "classpath": "/rest/v1/domain/nservices",
    "name": "platform.PerfmonService",
    "method": "test",
    "request": {"a":1,"b":"2","cc":[{"d":100,"e":"200"},{"f":300}]}
  }
]

Response to inquiry:

[
  "rest_result",
  {
    "qid": "16066361-dfc0-49f6-b734-9b3dda09472e",
    "data": {
      "result": "ok",
      "code": "success",
      "response": {"a":"zxcvzxcvzxcv"}
    }
  }
]

Configuring a connection for executing REST requests

General view of the request:

[
  "setup_rest",
  {
    "qid": 0.1234,
    "skip_response_entity": true,
    ...
  }
]

Possible options are query fields:

skip_response_entity - allows a specific web socket connection to disallow sending a full entity in response to create, replace, update operations. In this case, create still sends back an entity with a single "id" field, other requests return a simple 'ok'.
hrkey - sets the key for hashring-selection of the modification operation handler process. The entity identifier is used by default. It is used to organize parallelization of modification operations processing and reading of a particular entity (integrity_mode: async, sync_fast_read, sync_fast_notify). Binding to a specific process handler allows preserving the sequence of operations important for the client system during processing and in notifications. A separate key can be used to preserve guaranteed preservation of a sequence of operations with several different class entities within a single super-operation known to the client system.

References

REST-API for dynamic class collections
General purpose functions for filter and aggregation base
Aggregation functions