Content
API definition
GetDeviceList
Get the list of all Smart Access Points.
RequestGetAll
Request the SmartAP to send a complete getAll (current model state) to the cloud.
It is important that this is not required to get the data-model. It is just exposed as "fallback”in case the model is not in sync. Otherwise it might be that the API-User is causing unnecessary load.
GetConfiguration
Get configuration for the Smart Access Point, this includes the schema for all devices, channels and data points, the building structure and current user information.
CreateUserWithPermissionsMethod
Create a new user in the SmartAP with permissions defined by scope names. The created users represents a service or entity in the cloud that wants to direct further calls towards the SmartAP through IoTHub. The user on the SmartAP is disabled by default and must be enabled manually by the customer to express consent to use the cloud service. This behavior is based on the protocol for other ISPf services that require manual confirmation as well. The call returns a success if the user already exists.
CreateBackup
Trigger the upload of a backup from the SmartAP to the cloud.
RestoreBackup
Download of a backup from the cloud. This call does not apply the backup, it just downloads it to the SmartAP so that it can be applied manually. Automaticly applying a backup is not supported by welcome IP because it might require manual interaction with the UI for device conflict resolution.
SetDataPointMethod
Set the value of one or multiple input datapoints. Each datapoint in the welcome IP installation is addressed by the device serial number, the persistent id of the channel (hex format) and the id of the datapoint inside the channel. The value is always formatted as string, even for numbers. Datapoint values will be applied in the order they are given in the payload.
RPCCreateCredentialMethod
Create QR/Pin code
RPCQueryCredentialMethod
Query QR/Pin code
RPCDeleteCredentialMethod
Delete QR/Pin code.
Telemetry
The welcome IP cloud API provides a websocket endpoint to enable the API user to get immediately informed about changes to datapoints or the configuration without polling.
In order to open a websocket, you require a websocket implementation that:
Supports providing headers to the connection request.
Supports HTTP redirect responses (NOTE: Take special care of this. Not all implementations support this out of the box, sometime is must be enabled in the configuration, sometimes it is not supported at all).
Note in particular that opening from a browser in javascript is therefore not possible with default javascript websocket implementations.
When these requirements are ensured, simply open a websocket with the correct authentication headers (see the samples for details), including a valid OAuth2 token on the websocket url (using the usual websocket schema wss:// instead of https://):
After this, you can receive websocket events on the opened websocket connection.
All queries inside the “subscription {…}” query are sent via WS directly – in such cases no REST API is used (in the playground it just looks like the same as the REST calls)
There is a graphql-ws-protocol: https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md
A typical query looks like follows (could also be done using the ws-integration in Postman):
Init