Documentation structure

Each part of this documentation is divided into two main sections:

Events

The event section contains all events that can be sent over the websocket module. All events have the type parameter and can be identified and parsed accordingly. Events do include some more advanced access checking within the coldwave backend environment. The documentation includes what resource is required to receive those events. All events require read permission for that resource. Furthermore, device and service access is considered as well. If you do not have access to device XY you will not receive events that were triggered by that device. The documentation here should be used to implement a parser that handles incoming events. Different events can be selected via a click on the specific event in the header of the event section.

API

The API section contains all the possible endpoints a features offers. While the GET endpoints are less important due to the fact that the state of the application will be communicated via websocket, other endpoints, that do create or do delete resources are documented here. The API section is split into some subsections.

Subsection	Description
Access	The access section contains information what is required to access the API. The access consists of a resource identifier, e.g. meta and an action, e.g. read.
URL Parameter	Parameter that are part of the URL. Most commonly used for identifiers, e.g. /meta/<<DEVICE_IDENTIFIER>> to access the meta data of a specific device identifier.
Query Parameter	Query parameter that can be used to change the handling of the request as described within the description of the parameter. An common example is the query parameter depth. When added to some GET requests it increases the depth of the nested information requested. Therefore, it allows to get more data with less requests.
Request Body	The request body section documents the request body that is required to be added to the request.
Response	The response section will describe the expected return value for a given request. Sometimes the response code 204 is used to indicate a successful operation. This code is sent to reduce network traffic.

Tables

The documentation uses tables when describing objects, that are used throughout different parts of the backend application. Those can be options for the config, query-parameter, events or any other thing. While the tables are pretty self-explanatory most of the time, there are a few special types used in the tables, that will be explained in a little more detail here.

Documentation style: tables

An alternative is used, when a key accepts more than one object as a vaid value, for example when adding a user or an api-token to be used, as in the following example:

Name	Description
auth	The auth object that contains the means to authenticate this backend against the update server.
Alternative 1object
auth.type stringconstant	Constant value: API_KEY
auth.key string	The API key used to sign requests to the update server with.
Alternative 2object
auth.type stringconstant	Constant value: USER
auth.name string	The name of the user for the update server.
auth.password string	The password for the user for the update server.

The resulting object could be using a simple user as authentication method:

{
  "auth": {
    "type": "USER",
    "name": "admin",
    "password": "password"
  }
}

or an api key:

{
  "auth": {
    "type": "API_KEY",
    "key": "key"
  }
}

Most, if not all, of these alternative objects offer a key to more easily parse the payload. In this case the typeis used to differentiate between user and api key.

Dictionary

Some modules allow setting arbitrary data that can be used to transport any information in any schema. For example the meta module. The hint dictionary is given under the name of the key.

Name	Description
dictionary dictionary	An object that allows key-value storage. The keys are strings while the values can be of any type.

The above schema would accept an object like the following (or any other object for the matter):

{
  "dictionary": {
    "foo": 1,
    "bar": true
  }
}

Array

Arrays or list are also pretty common throughout the modules. There are arrays with simple data types (string, numbers, etc.) and more complex arrays. The former simply contains an array tag and a type-tag. While the latter unwraps on element and shows every array-item-property. Note the [ ] in the path of the name.

Name	Description
user array	A list of user.
user.[ ].name string	The username.
user.[ ].age number	The age of a person
roles arraystring	All available roles.

The recent schema accepts, for example, this object:

{
  "user": [
    {
      "name": "admin",
      "age": 23
    }
  ],
  "roles": [
    "admin",
    "client"
  ]
}

Record

Records are special objects where the keys of an object can be freely chosen but contain information. In the following example the key will be used as the username and the value for that key must follow a certain structure. This is marked in the path as a # character.

Name	Description
user dictionary	Record of users where the key is the username.
user. #.age number	The age of the user.

The object

{
  "user": {
    "adminUser": {
      "age": 35
    },
    "testUser": {
      "age": 31
    }
  }
}

would satisfy the above constrains. It contains two exemplary user. In terms of information, comparing the array and the record, there is no big difference. However, for a faster lookup by username the latter version is preferred and therefore used in some modules.

References

References are used where there is a rather nested or recursive object definition. They can be thought of as adding a new type to the available type definitions locally. In the example below the type Person is added and referenced in the employee key as well as in the recursion for the persons mother and father. The reference documentation feature is currently only used within the alarm module.

Name	Description
employee Person	A person object

References

Person

Name	Description
father Person	The persons biological father.
mother Person	The persons biological mother.