REST API

The API is a software interface that allows you to use the product’s functionality when accessing external systems. In this case, the platform API provides the ability to work, interact and use the platform entities and their data in such external systems like CRM, ERP, web portals, mobile and web applications, etc.

Version 1

The current version of the API corresponds to version 1. Data is exchanged using messages encoded in json using the HTTP and WebSocket protocols. The path of all HTTP methods has the api/v1 prefix.

Each system object has its own ObjectId identifier in bson format (24 hexadecimal characters, for example, 58238a935baa56173b24f0e4), which is stored in the _id field. The identifier is assigned by the system and assigned to the resource at the time of its creation. It can’t be changed in the future, since the identification of objects and the transition to links to them occur by their identifiers.

Entity ID can be viewed in the “Administration” menu, in the “Editing” tab. When you select a specific entity, the identifier of this entity will be displayed in the upper left corner. If you click on it, the entity configuration with all its fields and their values will be displayed on a separate page.

In addition to the identifier, all system objects have four fields:

• owner, owner id;
• group, owner group id;
• access, access-list;
• branch, access group list.

When generating requests for interaction with the platform, the key methods are:

• GET – getting data from a resource;
• POST – creation and placement of a new resource;
• PATCH – updating a resource, adding one or more changes to a specified fragment of a resource;
• DELETE – resource deleting.

However, only two HTTP headers are always indicated for all methods in the table below .

Headline	Function
Content-Type: application/json	Specifies the format and way of representation of the entity. In the platform system all entities are formed in json format, in which they are displayed on the graphical plaform interface in the “Code” tab, are specified in the HTTP request and are given in the server response.
Authorization: Bearer {token}	Specifies the data for authorization. To transfer the token in the request through the header, the Bearer HTTP scheme is used, after the name of which the issued token is indicated. The token can be issued through your account in the “Tokens” section.

The implementation and actual application of these methods are described below.

Entity Creation

To register a new entity in the system, you must send a POST /api/v1/:store request indicating certain fields. The prefix:store indicates the name of the entity. Fields are indicated in the request body, accordingly, only those necessary for the user can be indicated. However, it is worth considering that for some entities there are required fields.

Request

POST /api/v1/:store HTTP/1.1
Content-Type: application/json

{
  "some_field":"SOME_VALUE",
  "other_field":"OTHER_VALUE"
}

Entity getting

To get an entity, you need to send a request GET /api/v1/:store/:id. In this request, the prefix: :id indicates the identifier of the ObjectId, entity assigned to it by the system. The message body doesn’t need to be specified.

Working with lists

In the process of working with the HTTP platform API, receiving and sending data through its use, it may be necessary to narrow down the selection of data to which the user has access, to select more specific or, conversely, more general information about the system entities. For this purpose, certain parameters and their values can be indicated in the start line of the request, allowing them to narrow or expand the selection.

When requesting any list of entities, the maximum number of returned objects is 10000. Subsequent unloading is carried out with an indentation. For example, :store?offset=10000 will unload 10000 entities, starting from 10001 inclusive.

The limit parameter allows you to set a limit on the number of uploaded objects. For example, :store?offset=10000&limit=1000 will unload 1000 entities, starting from 10001 inclusive.

The only  parameter allows you to specify a list of fields to display. For example, :store?offset=10000&limit=1000&only=name,description will unload 1000 entities, starting from 10001 inclusive. In addition, each entity will contain _id, fields, as it is required, name и description.

The meta parameter allows you to get the total number of entities in the collection, the first and last entity. This parameter can’t be used together with offset и limit. Example usage: :store?meta=true.

To request a list of objects created in a certain period, the from и to parameters are used – the lower and upper boundary of the interval. Similarly to these parameters, parameters begin и endcan be set. They have an equivalent meaning.

For each of these two parameters, certain time points are indicated, which can be set either in Unix Timestamp format or in ISO 8601 format. In the first case, the number of milliseconds spent since midnight (00:00:00 UTC) is given on 1 January 1970. In the second case, the date and time are explicitly given, taking into account the form YYYYY-MM-Ddthh:mm.

Example

GET /api/v1/:store?from=1567285200000&to=1567285300000 HTTP/1.1

In the example, a list of entities entered instead of the prefix: :store,will be returned, with all the necessary fields. Using time parameter data can be useful if you need to receive data packets and access them.

Entity change

To change an entity field, send a PATCH /api/v1/:store/:id request indicating the desired fields. It is worth considering that there are fields that are required for each entity and can’t be changed in this way. One of them _id, access, owner, group, branch.

Request

PATCH /api/v1/:store/:id HTTP/1.1
Content-Type: application/json

{
  "some_field":"NEW_VALUE",
  "other_field":"NEW_OTHER_VALUE"
}

Entity deleting

To delete an entity, you must send a DELETE /api/v1/:store/:id request without specifying additional HTTP headers and fields in the request body.

Authentication and Authorization

Authorization using Cookies

To authorize a user using the HTTP Cookies mechanism, you must send the POST /api/v1/auth method with your own username and password. In case of successful verification of credentials, the server will return a response with the code 200 and the Set-Cookie header. It will indicate the identifier of the session and the time of its expiration. The identifier of this session is indicated in subsequent requests to the service in the Cookie header, taking into account the specified time.  After the session expires, you need to send the POST /api/v1/auth method again.

Request

POST /api/v1/auth HTTP/1.1
Content-Type: application/json

{"login":"<API USER LOGIN>","password":"<API USER PASSWORD>"}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: sid=<SESSION ID>; Path=/; Expires=Thu, 1 Jan 2015 00:00:00 GMT; HttpOnly

{"sucess":true}

Authorization using Token

To authorize a user using tokens, you need to send the POST /api/v1/auth/token method с указанием собственного логина и пароля. with your own login and password. In case of successful verification of credentials, the server will return a response with the code 200 and the value of the issued token specified in the token field.

The received token must be added to the subsequent requests in the HTTP  Authorization header:

Authorization: Bearer <ACCESS TOKEN VALUE>

Request

POST /api/v1/auth/token HTTP/1.1
Content-Type: application/json

{"login":"<API USER LOGIN>", "password":"<API USER PASSWORD>"}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "sucess": true,
  "type": "access",
  "token": "<ACCESS TOKEN VALUE>",
  "issuedAt": 1494594580646,
  "expiresAt": 1494680980646
}

WebSocket

After authentication, a WebSocket session request can be sent. To do this, a request is sent to the address /socket.io/?EIO=3&transport=websocket using the WSS protocol with the Connection:Upgrade and Cookie.

A message of type 0 with connection parameters of the form: 0{"pingInterval":25000,"pingTimeout":60000} will come to the installed WebSocket connection.

According to this message, the client should send a type 2 message every 25 seconds, to which the server should send a type 3 message within 60 seconds, otherwise the connection is considered lost.

HTTP Status Codes

In the response received from the web server, in addition to the HTTP version, a status code is always displayed that describes the result of the request sent to the server. Among all existing status codes, five classes are distinguished, each of which forms a certain group of informative messages depending on the current status of the request. Accordingly, there are a large number of status codes, and at the same time, possible responses from the server. Below are four of the most common.

If the HTTP request is successfully executed, the service will respond with a message with the code 200. In this case, the size of the entity content in bytes will be indicated in the HTTP header, and the response data in the message body.

HTTP/1.1 200 OK
Content-Length: ~

{"sucess":true}

If the method hasn’t been authenticated before the send or the session has expired, the service will respond with an error with code 401.

HTTP/1.1 401 Unauthorized
Content-Length: ~

{
  "success": false,
  "code": "401",
  "message": "Unauthorized",
  "tags": [
    "error_unauthorized"
  ]
}

When the HTTP method is not available to the user with the API access settings provided to him, the service will respond with an error with code 403.

HTTP/1.1 403 Forbidden
Content-Length: ~

{
  "success": false,
  "code": "403",
  "message": "Forbidden",
  "tags": [
    "error_credentials",
    "error_forbidden"
  ]
}

If the user requested a non-existent resource, the service will respond with an error with code 404.

HTTP/1.1 404 Not Found
Content-Length: ~

{
  "success": false,
  "code": "404",
  "message": "Not Found",
  "tags": [
    "error_not_found"
  ]
}