Application programming interface (API) (EN) v.2

Content of this article:

1 Query format
2 Answer format
3 Basic query types
4 Structure of the monitoring system
5 JSON format

API Content:

The Vutlan systems web interface uses HTTP / HTTPS protocols for information exchange.

POST the request is used to query and to change the current settings of the monitoring system. In this case, a request is made from the client part (web interface in the browser) to the server part (CGI program). Current parameters are returned by the server part in XML format. AJAX technology can be used for exchange.

Query format

When accessing the server, you need to specify the CGI program to which the request is being sent. For general queries, this is "engine.htm". Thus, the full path will be http://192.168.0.193/engine.htm.

The query is sent as an HTTP POST request and consists of fields. The query field is the field name and field value separated with the '=' sign. A query can contain multiple fields, in this case, the fields are separated with a '&' sign.

Answer format

The response from the server part to the client part is transmitted as a document in *.xml format. The content of the XML document corresponds to the command passed in the request. If the command fails to execute, the server part returns an error in the form:

<error type="error description" />

Here, "error description" is a string that takes a value:

'no error': no error. This type is transmitted by the monitoring system when the command is successfully executed (setting new parameters).
'error': general execution error, reason not specified.
'invalid request': the request type is not supported - the value of the parameter `querytype` is incorrect.
'authorization error': authorization is required to execute the request, or the transmitted key is not correct, or the user session is closed (for example, after the time has elapsed).
'access error': this command is not allowed or access to this resource is denied, the user has insufficient rights.
'some parameters are not specified': all required parameters of the request were not passed.
'wrong size': one of the request attributes has an unsupported size.
'wrong data': one of the request attributes has an incorrect value or an incorrect format.
'user already exists': error when registering a new user - a user with this name is already registered in the system.
'file not found': file open error, file not found.
'directory not found': directory opening error, directory not found.
'module is not loaded': The requested module is missing.
'not found': The requested object was not found.
'resource busy': The requested object is busy or not available.
'not supported': action not supported.
'answer error': internal device response error.
'state error': the wrong state of the object (element, module, etc.), the object is disabled or in an undefined state.
'bad request': server error 400.
'forbidden': server error 403.
'internal server error': server error 500.

The type field can be absent, this form is equivalent to the common error:

<error type = "error" />

Basic query types

The main fields of the query are:

k - key, determines the level of access in the system (profile), for the user who sends the request, and is issued during authorization;
querytype - the type of the request contains the command that the server part should execute;
The presence of other fields and their names depend on the type of request.

Structure of the monitoring system

The structure of the monitoring system is, in general, a set of objects of the following types:

element - a structural unit in the system (sensor, device, e-mail notification, etc.);
module - a combination of elements that are combined in the system according to a structural feature (composite sensor, module uniting cameras or SMS notifications, etc.);
group - a combination of objects that are united in the system according to an arbitrary characteristic (user-defined).

JSON format

Device families VT855i, VT960i, and VT855t support API requests in JSON format.

When accessing the server, you need to specify the CGI program to which the request is being sent. For general queries, this is "engine.htm". Thus, the full path will be http://192.168.0.193/engine.htm.

To exchange messages in JSON format, the MIME content type must be specified in the POST request header as 'Content-Type: application/json'.

Input requests should have the following format:

{
  "auth":{
    "name":"guest", 
    "p":"guest", 
    "h":"35675e68f4b5af7b995d9205ad0fc43842f16450"
  }
}

Here "auth" is the querytype name of the request type.

Next comes the "key: value" parameter pairs corresponding to the request type. You can see the names of these fields in the API description.

Response messages have the following format:

Here "user" corresponds to the tag name for the XML structures defined in the API. Next, follow are "key: value" parameter pairs.

Not all requests in JSON format are supported yet. As far as possible, we will fill in these gaps.
These requests are not yet implemented in JSON format:

all duplicator requests - dublcrtinfo, dublsettings, dublfirmware, dublsystemget, dublunitadd, dublunitdel, dublgetdb, dublreset;
all logic schemes requests - getlogic, dellogic, addlogic, disablelogic, offlogics, onlogics;
getelementlist.