REST API approaches (rest / v1)
REST request API scheme
/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>.
-
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.
POST /rest/v1/<CHAPTER>/.../<COLLECTION> HTTP/1.1
Content-Type: application/json; charset=utf-8
<resource>
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).
GET /rest/v1/<CHAPTER>/.../<COLLECTION> HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
<resource>,
<resource>,
...
]
| Name | Value type | Description |
|---|---|---|
|
|
Filter of elements by field values. Specified as a JSON structure. Examples:
Supports search conditions for strings:
Supports search conditions for numbers:
Supports search conditions for values of type For list fields, uses the criterion that the list from the filter is included in the value list: 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.
|
|
|
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:
|
|
|
List of resource fields to return. By default all fields are returned. Examples:
|
|
|
Offset in the output. The zero-based sequence number in the filtered ( Example:
|
|
|
Maximum number of resources to return from the filtered ( Example:
|
|
|
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:
|
|
|
When set to The count is calculated after applying the filter: with the Example return value:
{
"count": 5
}
Example: |
|
|
When set to 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: |
GET resource
Returns a specific resource. Using parameters, the returned field composition can be narrowed (mask) and the output format transformed (flat).
GET /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
<resource>
| Name | Value type | Description |
|---|---|---|
|
|
list of fields to output. Specified as an enumeration of fields. If the parameter is not specified, all fields are returned. |
|
|
transformation to flat form. |
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.
PUT /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
Content-Type: application/json; charset=utf-8
<resource>
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!put HTTP/1.1
Content-Type: application/json; charset=utf-8
<resource>
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'.
PATCH /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
Content-Type: application/json; charset=utf-8
<resource>
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!patch HTTP/1.1
Content-Type: application/json; charset=utf-8
<resource>
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.
DELETE /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!delete HTTP/1.1
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.
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, headerX-Era-Dry-Run: true. For create and modify, the content is the resource asGETwould 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 withdry_runis rejected with code400— 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.
Content-Disposition: attachment; filename="my file.txt"
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'
<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'
<METHOD> /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>/<FIELD> HTTP/1.1
<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.
<CUSTOM_METHOD> /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
For example, LOOKUP /rest/v1/iam/users HTTP/1.1.
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!<CUSTOM_METHOD> HTTP/1.1
For example, POST /rest/v1/iam/users!lookup HTTP/1.1.
-
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.
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– forPUT -
patch– forPATCH -
delete– forDELETE -
head– forHEAD -
similarly for any specific methods (e.g.
SWITCH <EndPoint>→POST <Endpoint>!switch)
-
Content-type in requests
-
multipart/form-dataandapplication/octet-streamfor files; -
application/jsonfor resources; -
application/x-www-form-urlencodedfor resources, assumes adataparameter containing the target resource.
| HTTP Verb | Content-Types |
|---|---|
|
|
|
|
|
|
|
|
|
|
REST response API scheme
Error response 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"}
| HTTP code | error_code | Description |
|---|---|---|
|
Error in request parameters |
|
|
|
Authentication required |
|
|
Access to resource/endpoint denied |
|
|
Resource/endpoint not found |
|
|
Resource already exists |
|
|
The specified resource parameters cannot be applied |
|
|
Server error while processing the request |
Content-type in responses
-
application/jsonfor resource output, including errors, and.jsonfiles with the corresponding content type); -
application/octet-streamfor 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.
| HTTP Verb | Content-Types |
|---|---|
|
|
|
|
|
|
|
|
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".