REST API approaches (rest / v1)

REST request API scheme

URL path format
/rest/v1/<CHAPTER>/<RESOURCE_PATH>
  • v1 – API section backward compatibility version;

  • <CHAPTER> – section name;

  • <RESOURCE_PATH> – path in the resource tree to the endpoint, for example /selectors/<SELECTOR_ID>/participants/<PARTICIPANT_ID>.

Basic principles
  • Collection names are in plural form;

  • Collections always contain elements of one type;

  • HTTP verbs are used for create/read/update/delete (CRUD) operations.

Section navigation

GET on an intermediate path level with a trailing / (up to 7 levels after /rest/v1/) returns an array of child element names available to the current user by rights and domain type: GET /rest/ → ["v1"], GET /rest/v1/ → list of sections, GET /rest/v1/uc/ → section resources.
Without authorization only public elements are returned; a nonexistent path returns 404.

POST collection

Creates a new resource in the collection and returns it in the response.
The new resource being created is passed as the request body in JSON format (Content-Type: application/json) or as JSON in the data parameter (Content-Type: application/x-www-form-urlencoded).
The field composition must include all required fields and may include an identifier. If no identifier is specified, a new one is generated.
The response returns the created resource, including automatically generated field values.

Request format
POST /rest/v1/<CHAPTER>/.../<COLLECTION> HTTP/1.1
Content-Type: application/json; charset=utf-8

<resource>
Successful response format
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

<resource>

GET collection

Returns a list of resources from the collection with a limited set of fields.
Using parameters, it can be additionally filtered (filter), sorted (order), paginated (offset, limit), have the returned field composition narrowed (mask), and the output format transformed (flat).

Request format
GET /rest/v1/<CHAPTER>/.../<COLLECTION> HTTP/1.1
Successful response format
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  <resource>,
  <resource>,
  ...
]
Table 1. Parameters
Name Value type Description

filter

object

Filter of elements by field values. Specified as a JSON structure.
Only resources with the specified values are returned.
If the parameter is not specified, all data is returned.

Examples:

  • filter={"id":"some_id","name":"some_name"}

  • filter={"id":"some_id","opts":{"a":"some_value":}}

  • filter={"id":"some_id","opts.a":"some_value"}}

Supports search conditions for strings:

  • "abc" – exact match;

  • "a%bc%" – an arbitrary string starting with "a" and containing "bc" inside;

  • "ab|cd|ef" – exact match to either "ab", "cd", or "ef";

  • "/reg/abc.+" – regular expression: an arbitrary string containing "abc" and one more character;

  • "/reg/i/^abc.*" – regular expression: an arbitrary string starting with "abc", "ABC", "aBC", etc.;

  • "/reg//a/bc$" – regular expression: an arbitrary string ending with "a/bc".

Supports search conditions for numbers:

  • 3 – exact number value;

  • 3.01 – exact number value;

  • "3.01" – exact number value;

  • "1~35" – range of number values from the segment [1,35];

  • "~-5.01;-2~5;15~" – range of number values from the set (-inf,-5.01] U [-2,5] U [15,+inf).

Supports search conditions for values of type bool: false, 1, true, "true", "tRUe", etc.

For list fields, uses the criterion that the list from the filter is included in the value list: ["ab","cd"]

For object fields, uses the criterion that the field values specified in the filter match the values of the corresponding object fields, allowing the actual conditions for strings, numbers, bool, lists, and child objects.

Alternatively, a filter format similar to /rest/v1/model can be used.

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

  • filter=["or",["and",["in",["property","status"],["list",initial","active"]],[">",["property","count"],10]]]

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

order

array<object|str>

Sorting of resources in the specified order. Applies a sequence of fields, each with a defined sorting direction; when values match, the next field is applied.

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

str

List of resource fields to return. By default all fields are returned.
Composite fields may be specified either entirely or with the nested options of interest indicated through a dot, regardless of the flat parameter value.

Examples:

  • mask=id,name,ext

  • mask=id,name,ext.ct,ext.lwt

offset

int

Offset in the output. The zero-based sequence number 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 return 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 discovered elements without applying the offset parameter.

Example:

  • limit=2

flat

bool

Transformation to flat form: values in the form of an option set are expanded into first-level keys:

"opts":{"a":true,"b":10} => "opts.a":true,"opts.b":10

Example:

  • flat=true

countonly

bool

When set to true, only the number of discovered resources is returned.

The count is calculated after applying the filter: with the filter parameter, the number of records matching the filter is returned, not the total number in the collection.

Example return value:
{
  "count": 5
}

Example: count=true

export

bool

When set to true, the object returns field values in the form in which they can be imported later.

Example return value:
{
  "id": "e7adf0aa-05b7-8163-948c-3392a9660db9",
  "name": "Administrator",
  "login": "admin",
  "pwd": "ha_v=1;0307030703070309BFB39B099674A...",
  "timezone": "default",
  "opts":{
    "allow_script_crud": true,
    "roles":["admin", "scripteditor", "monitor"]
   }
}

Example: export=true

GET resource

Returns a specific resource. Using parameters, the returned field composition can be narrowed (mask) and the output format transformed (flat).

Request format
GET /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
Successful response format
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

<resource>
Table 2. Parameters
Name Value type Description

mask

str

list of fields to output. Specified as an enumeration of fields. If the parameter is not specified, all fields are returned.
Example: mask=id,name

flat

bool

transformation to flat form.
Example: flat=true

PUT resource

Replaces the resource with the specified identifier in the collection completely. The identifier cannot be replaced.
The new resource is passed as the entire request body. If the resource did not exist, it is created with the specified identifier.

The method is unavailable for domain center collections; instead, strictly use:
* to create an entity: POST of the collection endpoint with the identifier passed in the entity body;
* to modify entity fields: PATCH of the entity endpoint with the identifier passed in the endpoint URI.

It is also used to place files with the specified name.

Request format
PUT /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
Content-Type: application/json; charset=utf-8

<resource>
Fallback request format
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!put HTTP/1.1
Content-Type: application/json; charset=utf-8

<resource>
Successful response format
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

<resource>

PATCH resource

Partially merges the resource with the specified identifier in the collection. The identifier cannot be replaced.
The request body contains a resource in JSON format with only the fields to change.
The response contains the new resource with all fields.

For dynamic data model collections, even complex entity fields are replaced entirely.
Domain center collections have composite fields (e.g. opts, ext, lic, security, etc.) where keys are merged at the first level. To remove a key of a composite field, set it to 'null'.

Request format
PATCH /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
Content-Type: application/json; charset=utf-8

<resource>
Fallback request format
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!patch HTTP/1.1
Content-Type: application/json; charset=utf-8

<resource>
Successful response format
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

<resource>

DELETE resource

Deletes the resource with the specified identifier from the collection. Nothing is returned in the response content.

Request format
DELETE /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
Fallback request format
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!delete HTTP/1.1
Successful response format
HTTP/1.1 204 No Content

Check without saving (dry_run)

The dry_run parameter in the request string performs all checks for creating, replacing, modifying, or deleting a resource but saves nothing: neither the resource nor the change log; notifications to subscribers are not sent, and counters (auto-increment fields) are not consumed.

Supported by POST, PUT, PATCH, DELETE (and their fallback requests) for static class collections (domain center) and dynamic data model entities. Access rights are the same as for writing.

Request format
POST /rest/v1/<CHAPTER>/.../<COLLECTION>?dry_run=true HTTP/1.1
  • Values: true, 1, or no value — check; false, 0 — normal write.

  • A check error is returned with the same code and content as on write.

  • Successful response: 200 OK, header X-Era-Dry-Run: true. For create and modify, the content is the resource as GET would return it after writing (on create — with a one-time identifier that is not saved). For delete — an empty object {}.

  • For other methods and endpoints, including attachments, specific methods (CLEAR, SETUP, LOOKUP), and batch operations, a request with dry_run is rejected with code 400 — the write is not performed.

  • The check does not reserve values: uniqueness is checked at request time and finally on write.

  • Results of external write actions are not checked: when creating a domain, no database is created and no template is copied; file copying when creating from a template is not performed.

File attachments

Some collections have attachment fields.

Such fields can be:
* single — the field endpoint immediately provides access to the attachment;
* multiple — the field endpoint provides access to the attachment directory.

File upload can be performed in requests with Content-Type application/octet-stream or multipart/form-data.
In storage the file is stored under a special name — the last part of the URL path when uploading to the attachment directory, or "content" when uploading to a single attachment field.

The original file name is passed in the Content-Disposition header and saved in metadata.
When downloading an attachment with the attachment parameter in the GET request string, the file is downloaded as an attachment preserving the original name from metadata.
Otherwise the content is returned with a Content-Type corresponding to the uploaded file name extension, for example text/plain for *.txt or image/png for *.png.

Example 1. Example for application/octet-stream (main HTTP request headers)

Content-Disposition: attachment; filename="my file.txt"

Example 2. Example for multipart/form-data (headers of a specific part from the HTTP request body)

Content-Disposition: form-data; name="any"; filename="my file.txt"

Fields with single attachments

GET, POST, PUT, DELETE, and optionally METADATA methods are used for attachments (for domain center collections, e.g. /rest/v1/domain/roleapps/attachment, /rest/v1/domain/mservices/attachment).
See also Attachment file, property type 'attachment'

Endpoint format
<METHOD> /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>/<FIELD>[/<FILE_NAME>] HTTP/1.1

Fields with multiple attachments

GET, POST, PUT, DELETE, and optionally METADATA methods are used for attachments (for domain center collections, e.g. /rest/v1/uc/ivrscripts/attachments, /rest/v1/service/svcscripts/attachments).
See also Attachment file, property type 'list of attachments'

Collection endpoint format (GET, POST methods)
<METHOD> /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>/<FIELD> HTTP/1.1
Collection endpoint format (GET, PUT, DELETE, METADATA methods)
<METHOD> /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>/<FIELD>/<FILE_NAME> HTTP/1.1

Specific methods

Performs the specified specific method on the specified resource. The target response is in JSON format: a value, resource, or collection. Parameters are also specific to each method.

Request format
<CUSTOM_METHOD> /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1

For example, LOOKUP /rest/v1/iam/users HTTP/1.1.

Fallback request format
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!<CUSTOM_METHOD> HTTP/1.1

For example, POST /rest/v1/iam/users!lookup HTTP/1.1.

Commonly used specific collection methods
  • lookup – searches the collection for a resource by the specified key (unique) parameters and returns the identifier of a matching resource. The identifier is used in the resource endpoint.

Fallback requests

Can be used as substitutes when HTTP methods PUT, PATCH, DELETE, HEAD cannot be performed.
The fallback URL is built from the endpoint by adding the ! character after the resource or collection identifier. The request method is POST.

Fallback request format
POST /rest/v1/<CHAPTER>/.../<COLLECTION>!<FALLBACK_SUFFIX> HTTP/1.1

POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!<FALLBACK_SUFFIX> HTTP/1.1
  • FALLBACK_SUFFIX - target method in lowercase. Possible values:

    • put – for PUT

    • patch – for PATCH

    • delete – for DELETE

    • head – for HEAD

    • similarly for any specific methods (e.g. SWITCH <EndPoint> → POST <Endpoint>!switch)

Content-type in requests

Request Content-Type:
  • multipart/form-data and application/octet-stream for files;

  • application/json for resources;

  • application/x-www-form-urlencoded for resources, assumes a data parameter containing the target resource.

Table 3. Possible request content-types
HTTP Verb Content-Types

POST

  • application/json

  • application/x-www-form-urlencoded

  • multipart/form-data

  • application/octet-stream

PUT

  • application/json

  • application/x-www-form-urlencoded

  • multipart/form-data

  • application/octet-stream

PATCH

  • application/json

  • application/x-www-form-urlencoded

DELETE

  • No Content

  • application/json

  • application/x-www-form-urlencoded

Specific methods and POST for their fallback variants

  • application/json

  • application/x-www-form-urlencoded

  • multipart/form-data

  • application/octet-stream

REST response API scheme

Error response format

Format
{
  "error_code" : <INTERNAL_CODE>,
  "error_message" : <INTERNAL_MESSAGE>,
  "error_details" : <INTERNAL_DETAILS>
}
  • <INTERNAL_CODE> - internal (system) error code (int).

  • <INTERNAL_MESSAGE> - error description (str).

  • <INTERNAL_DETAILS> - optional attribute containing additional error parameters (object), for example {"field": "name"}

Table 4. Possible error codes
HTTP code error_code Description

400 Bad Request

Error in request parameters

401 Unauthorized

1401

Authentication required

403 Forbidden

1401

Access to resource/endpoint denied

404 Not Found

1401

Resource/endpoint not found

409 Conflict

1402

Resource already exists

422 Unprocessable entity

1405

The specified resource parameters cannot be applied

500 Internal Server Error

1409

Server error while processing the request

Content-type in responses

Response Content-Type:
  • application/json for resource output, including errors, and .json files with the corresponding content type);

  • application/octet-stream for file output in response to a download request (with the GET request parameter attachment=1);

  • other mime-types for file output according to their extensions.

Table 5. Possible response content-types
HTTP Verb Content-Types

GET

  • application/json

  • arbitrary mime-type for a file

POST

  • application/json

PUT

  • application/json

PATCH

  • application/json

REST API of the dynamic data model

The dynamic data model REST API extends the general approaches. More in the article "API overview".

REST API over WebSocket

An equivalent of the REST API is also available through WebSocket connections. More in the article "'rest' capability for WebSocket API".