Approaches to REST API (rest / v1)

API schema of request to REST

Format url path
/rest/v1/<CHAPTER>/<RESOURCE_PATH>

  • v1 – partition backward compatibility version API;

  • <CHAPTER> – section name;

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

Basic principles

  • Collection names in plural form (ang. plural);

  • Collections always contain elements of the same type;

  • Using HTTP Verbs for create/read/update/delete operations (CRUD).

POST collections

Creates a new resource in the collection and returns it in response to a request.
The new resource to be created is passed as a request body in JSON format (Content-Type: application/json) or JSON in parameter data (Content-Type: appication/x-www-form-urlencoded).
Field composition must include all mandatory fields and may include an identifier.
The response returns a created resource including the values of automatically generated fields.

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 collections

Returns a list of resources from a collection with a limited set of fields.
Can be additionally filtered (filter), sorted (order), paginated (offset, limit), returned fields narrowed (mask), output format converted using parameters (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 elements by field values. Defined as a json structure.
Only resources with the specified values will be returned.
If no parameter is specified, all data will be displayed.

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 terms for strings:

  • "abc" – exact match;

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

  • "ab|cd|ef" – an exact match of either ab'' or 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 in "a/bc".

Supports search terms for numbers:

  • 3 – exact number;

  • 3.01 – exact number;

  • "3.01" – exact number;

  • "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 of including a list from a filter in a list from a value: ["ab","cd"]

For object fields, it uses the criterion that the field values specified in the filter correspond to the values of the corresponding fields of the object, allowing the use of these conditions for specifying strings, numbers, bool, lists and child objects.

Alternatively, a filter format similar to the following may be used /rest/v1/model.

order

array<object|str>

Sorts resources in the specified order. Applies a sequence of fields, where each field defines a sorting direction, and applies the next field if the values match.

Examples:

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

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

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

mask

str

A list of resource fields to be output. By default, all fields are output.
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.

Examples:

  • mask=id,name,ext

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

offset

int

Issue offset. The number from zero in the filtered (filter) and sorted list of resources (order) from which to issue. Usually used in conjunction with the limit parameter for page-by-page 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

flat

bool

Convert to flat view: values as a set of options are expanded into a first-level key view:

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

Example:

  • flat=true

countonly

bool

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

Example of a return value:
{
  "count": 5
}

Example: count=true

export

bool

When set to true, the object returns the field values as they can be imported in the future.

Example of a 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", "crud", "scripteditor", "monitor"]
   }
}

Example: export=true

GET resource

Returns a specific resource. The parameters can be used to narrow down the return fields (mask) and transform the output format (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 be output. Specifies an enumeration of fields. If the parameter is not specified, all fields will be displayed.
Example: mask=id,name

flat

bool

planarization.
Example: flat=true

PUT resource

Modifies the resource with the specified identifier in the collection by full replacement. The identifier cannot be replaced.
The new resource is passed as the entire request body.

Used mainly for placing 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>
Format of a fallback request
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

Modifies the resource with the specified identifier in the collection by partial overlay. The identifier cannot be replaced.
A JSON-formatted resource containing only the fields to be modified is passed as the body of the request.
A new resource with all fields is returned as the content of the response.

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

<resource>
Format of a fallback request
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

Removes 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
Format of a fallback request
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!delete HTTP/1.1
Successful response format
HTTP/1.1 204 No Content

Specific methods

Executes the specified specific method on the specified resource. Target response in JSON format: 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.

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

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

Specific collection methods frequently used

  • lookup – searches for a resource in the collection by key (unique) specified parameters, returns the identifier of the matching resource. The identifier is used in the EndPoint of the resource.

Fallback inquiries

Can be used as understudies when HTTP methods cannot be performed PUT, PATCH, DELETE, HEAD.
Fallback url is built on the basis of the endpoint with the addition of “!” after the resource or collection identifier. Query method – POST.

Request fallback 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 lower case. Possible values:

    • put – for PUT

    • patch – for PATCH

    • delete – for DELETE

    • head – for HEAD

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

Content-type in queries

Content-Type inquiries:

  • multipart/form-data and application/octet-stream for the files;

  • application/json for resources;

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

Table 3. Possible content-type requests
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

API response schema REST

Erroneous 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), e.g. {"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 the resource/endpoint is denied

404 Not Found

1401

Resource/endpoint not found

409 Conflict

1402

The resource already exists

422 Unprocessible entity

1405

The specified resource parameters cannot be applied

500 Internal Server Error

1409

Server error during request processing

Content-type in response

Content-Type responses:

  • application/json to output resources, including errors, and .json files with the appropriate content type);

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

  • other mime-types to give files according to their extensions.

Table 5. Possible content-type responses
HTTP Verb Content-Types

GET

  • application/json

  • arbitrary mime-type for the file

POST

  • application/json

PUT

  • application/json

PATCH

  • application/json
  • Personalization
  • Increase font size
  • Decrease font size