|
|
|
---
|
|
|
|
title: Behaviour Details
|
|
|
|
---
|
|
|
|
# **Behavioral Details**
|
|
|
|
|
|
|
|
This section provides a more detailed description of specific behavioral aspects of the API. The following information is not necessary to use the demo.
|
|
|
|
|
|
|
|
This page contains a more detailed description of behavioural aspects of the API - the following elements are not generally necessary knowledge to use the demo.
|
|
|
|
---
|
|
|
|
|
|
|
|
# **Subscription Behavior**
|
|
|
|
|
|
|
|
## **Subscription Creation**
|
|
|
|
|
|
|
|
- When creating a datapoint subscription via a `POST` request, the API will **not create duplicate datapoint subscriptions**.
|
|
|
|
- Example: If a `POST` request subscribes to both a **device** and a **location** with the "expand" behavior (where a included location contains the device), it will **not result in duplicate callbacks** for the device´s datapoints.
|
|
|
|
|
|
|
|
- The **Subscription Secret** is a mandatory attribute. The API requires that the secret contains **at least one character**, while **whitespace or empty values** are not allowed.
|
|
|
|
|
|
|
|
## **Subscription Expiration**
|
|
|
|
|
|
|
|
- The expiration lifetime of a subscription is verified **both before sending callbacks** and **when creating a subscription**.
|
|
|
|
|
|
|
|
- A **lifetime of 0** results in an **arbitrary, very long lifetime** for the subscription.
|
|
|
|
|
|
|
|
## **Subscription Deletion**
|
|
|
|
|
|
|
|
- As per the specification recommendation, **datapoint subscriptions** will be **dropped** when a **new semantic export** is uploaded.
|
|
|
|
|
|
|
|
- The new semantic export may not include the same datapoints as the previous export
|
|
|
|
|
|
|
|
## **Subscription Resource Expression**
|
|
|
|
|
|
|
|
# **Subscription behaviour** #
|
|
|
|
## Subscription creation ##
|
|
|
|
- A subscription POST to create datapoint subscription will not create duplicates
|
|
|
|
Example: The subscription POST subscribes to a device aswell as a location with expand behaviour containing the device, will not result to duplicate callbacks
|
|
|
|
- Subscription Secret is a mandatory member, the API requires atleast one character with whitespace/empty not beeing accepted
|
|
|
|
- According to the specification, **not all attributes** of a subscription must be expressed in the subscription resources.
|
|
|
|
|
|
|
|
## Subscription expiration ##
|
|
|
|
- The expiration lifetime is checked before sending callbacks and when creating a subscription
|
|
|
|
- Lifetime 0 results in a arbitrary very long lifetime of the subscription
|
|
|
|
- For instance, the result of a request to **/subscription/{subscriptionId}** may **omit the secret attribute**.
|
|
|
|
|
|
|
|
## Subscription deletion ##
|
|
|
|
- As per recommendation of specification datapoint subscriptions are dropped when a new semantic export is uploaded
|
|
|
|
- The new semantic export may not contain the same datapoints as the previous
|
|
|
|
## **Subscription PATCH**
|
|
|
|
|
|
|
|
## Subscription resource expression ##
|
|
|
|
- As per specification recommendation not all attributes of a subscription are expressed in subscription resources
|
|
|
|
- For example a /subscription/{subscriptionId} result may not contain the secret member
|
|
|
|
- The API treats a callback client (or endpoint/receiver) as a combination of a **URL** and **Secret**.
|
|
|
|
|
|
|
|
- Creating two identical subscriptions will result in two **distinct Subscription Resources**, each with its own ID. However, **no duplicate datapoint callbacks** will be generated.
|
|
|
|
|
|
|
|
- Changing the **URL** or **Secret** of one subscription will not affect the other subscription resource.
|
|
|
|
- The API will treat these as **two different callback clients/endpoints/receivers** - a relevant change of value will now lead to two call backs beeing send
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
# **Date Time Value Expression**
|
|
|
|
|
|
|
|
- The API will use the **current time of the host system** to complete **DateTime values** into the mandated **ISO format**.
|
|
|
|
|
|
|
|
- This behavior is particularly relevant for **DPT Date** and **DPT TimeOfDay**, as well as for any **compound types** that use these datapointtypes.
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
## Subscription PATCH ##
|
|
|
|
- The API considers a call back client (or endpoint / receiver) as a combination of URL and Secret
|
|
|
|
- Creating two identical Subscriptions will result in two Subscription Resources with theire own Id but no duplicate Datapoint callbacks
|
|
|
|
- Changing one of the Subscription Resources URL or Secret will not lead to changes of the other Subscription
|
|
|
|
- Instead the API considers the Subscription related to two different call back clients/endpoints/receiver
|
|
|
|
# **Datapoint Values**
|
|
|
|
|
|
|
|
# **Date Time value expression** #
|
|
|
|
- The API will use the current time of the host system to complete Date Times to the mandated ISO format
|
|
|
|
- This is relevant for DPT Date and TimeOfDay and DPT which uses such as compounds
|
|
|
|
- Currently, **datapoint values are not persistently stored**.
|
|
|
|
|
|
|
|
- After a restart of the API, **all datapoint values will be reset**
|
|
|
|
|
|
|
|
# **Datapoint values** #
|
|
|
|
- Datapoint values are currently not persistently stored
|
|
|
|
- After a restart all datapoint values will not have a value
|
|
|
|
- Note: If the API was "offline" the values reliability is degraded, a persistant storage is therefore not implemented |
|
|
|
- **Note:** If the API has been **offline**, the reliability of the values is degraded. For this **persistent storage** is not implemented |
|
|
\ No newline at end of file |
