Serialization of Data between Client and API Interface

Both the Comet and the REST API interfaces share the same way of communication serialization using the JSON format. The only exception is calling SBA RPC methods which serve for sending and acquiring binary data from D2000 - in this case, the data is sent in a binary form. The JSON format is a universal format implemented almost in every programming language. Its advantage is not only native support in every browser but also easy readability for people since it is a text format. The disadvantage of the bigger capacity of a message in comparison with any binary format is minimalized by the use of a gzip compression implicitly supported by the REST and also the Comet API. 

Serialization of the Unival Type

The basic unit of data change between a client and the D2000 system is the Unival type - clustering basic object attributes in D2000. The following example of the unival value in the JSON format represents a value of a real number type with the Valid state.

{
  "type": "real",
  "value": 123.456,
  "status": ["Valid"]
}

Every Unival value has a clearly defined type with the use of the type attribute. In the case of sending Unival values into the D2000 system, the type attribute has to be always defined. The only exception is the possibility when we send instead of an object log of the Unival type the value directly, in our case 123,456. This value is automatically converted to the "real", type by the SmartWeb server since it is a value with a decimal point (in the case of sending a string, the type would be automatically set to the "text" value and in the case of sending an integer to the "int" value. 

123.456

The answer from the SmartWeb server never comes in this shortened log but in the "object" log with a defined type (type attribute) and a value (value attribute) if it is valid.

The type attribute may gain the following values:

The list of all attributes of the Unival object is in the following table:  

Implicit Conversion of Simple JSON Types to Unival Value

To simplify working through the API interface, it is possible to use simple types instead of Unival type objects as input values to the D2000 system. Such values have the validity attribute, the time of origin to the current time automatically set and other attributes gain their default value.

Defining of Returned Values from RPC Methods

The attribute returnFields defines the logical name of an output parameter required by a client from the server. 

In the figure, there is represented an example of the SimpleSum method calling by a client. The first two parameters are simple JSON types that are implicitly converted to right Unival values. The third parameter is an output one and the client defines in the returnAs attribute the logical name under which will be the output Unival value returned; in this case, it is the logical name "vysledok".

Optimization of the Content of the Returned Unival Value

Because of the minimization of transmitted data, the Unival objects standardly contain on the output from D2000 only type and value attribute (if the value is valid). In the case of need of other extended value attributes, which are provided by the D2000 system, it is possible to set the returnFields attribute when calling and name required attributes in it.  The value of the returnFields attribute has a format of a text field. Allowed values are in the following table.

Unival type Structure ("record") 

The value of the structure type has its values and attributes stored as a two-dimensional field (row, column). Values gain the type according to the definition of structure in the D2000 system. It does not use extended attributes alarmTime, flags, limitStatus, processAlarmStatus, status a valueTime. Instead of them, it uses attributes alarmTimes, flagsSets, limitStatuses, processAlarmStatuses, statusSets, valueTimes, which are a two-dimensional field and components have the same type as the original attributes. Other attributes used only in structures are definition and structType. The definition attribute (D2RecordDefinition object) is always automatically set on all structural values that come from the D2000 system. This attribute describes columns' names and their types in a structured variable. Columns' types in a structure are a simplified version of Unival types.

The structType attribute is a text attribute and defines the name of the D2000 object of the structure definition type. It is mandatory to set it for every structured value that is inputted into the D2000 system.

{
  "type": "record",
  "structType": "SD.Arr_Real_Text",
  "value": [[1, "One"], [2, "Two"], [3, "Three"]]
}

{
  "type": "record",
  "definition": {
    "columnTypes": ["integer", "text"],
    "columnNames": ["digit", "name"]
  },
  "value": [[1, "One"], [2, "Two"], [3, "Three"]]
}

Transformations of Time Rows

Time row is a one-column structure in which values are real numbers and have increasing time stamps set. When displaying time rows, all values from requested interval are often not necessary or required (especially because of performance).  For such needs, transformations of time rows are implemented which decrease the number of transmitted data. It is possible to request the transformation by setting the transformation attribute on the output structured value.

Downsampling

Downsampling is reducing the number of values according to the given step or to the given number of values. The used algorithm tries as much as possible to keep the course of the curve of the original time row and does not smooth the final curve as the common resampling using averaging.  

{
  "type": "record",
  "structType": "SD.Arr_Real",
  "returnTransformation": {
    "type": "lttb",
    "threshold": 100
  }
}

{
  "type": "record",
  "structType": "SD.Arr_Real",
  "returnTransformation": {
    "type": "lttb",
    "step": 86400
  }
}

OHLC

The OHLC (Open-High-Low-Close) algorithm transforms the output time row in a way that for every interval it finds first, maximal, minimal and last value. Optionally when using this algorithm, it is possible to set whether the intervals should be continuous (successive intervals have the first and the last value common - by default) or discrete - the discrete attribute and where should be the time stamp of the value representing the whole interval placed (the beginning "Start" or in the middle "Midpoint" - by default) - the timestampPlacement attribute. 

{
  "type": "record",
  "structType": "SD.Arr_Real",
  "returnTransformation": {
    "type": "ohlc",
    "step": 86400,
    "discrete": true,
    "timestampPlacement": "Start"
  }
}