Ux4iot exposes a REST API that you can use in your security backend and in your own apps to manage subscription workflow. These APIs are used by ux4iot-react hooks to communicate with security backends and ux4iot.
We recommend using the ux4iot-admin-node library when using the REST API. At the moment, we only support typescript.
The only time you will need to directly use the ux4iot REST api is in your security backend to forward grants and in your DevOps to ensure the ux4iot is running correctly. All other resources are mainly used by the ux4iot-react library.
In order to use the REST API you will need the Shared-Access-Key of the Ux4iot. You can find it as part of the ux4iot connection string. Get the connection string by using the left sidebar in your ux4iot instance.
There are api resources to perform actions against the IoTHub. They are only available if you use an IoTHub service connection string in your ux4iot deployment parameters.
The shared-access-key of the the connection string of your ux4iot instance
Grants
Grants authorize a session to subscribe to resources, patch desired properties and execute direct methods.
GrantRequest Types
GrantRequest types only differ in the "type" property. For Telemetry and DirectMethods you can add an additional property to restrict specific telemetry keys or direct methods respectively.
used to grant a specific telemetryKey. use null for all telemetry of the device
directMethodName
string | null
available on type: 'directMethod' used to grant a specific directMethod. use null for all direct methods of the device
Subscriptions
A subscription request lets a session subscribe to live data from the EventHub. Similar to GrantRequests, there are multiple SubscriptionRequest types:
You have to send a list of subscription requests as body. If this list contains an invalid subscription request, the entire request will fail without applying any subscription requests. If you have a missing grant for some of the subscription requests, they will be skipped.
The response will contain a body that gives you the list of applied subscription requests. If you have valid grants for all subscription requests, the response body will match your request body.
You have to send a list of subscription requests as body. If this list contains an invalid subscription request, the entire request will fail without removing any subscription requests. If you have a missing grant for some of the subscription requests, they will be skipped.
The response will contain a body that gives you the list of applied subscription requests. If you have valid grants for all subscription requests, the response body will match your request body.
If you have provided a IoTHub service connection string in your ux4iot deployment parameters and if there is no connection state found in the ux4iot's cache, ux4iot will also check the IoTHub for the connected property in the device twin for a last connection state.
These api resources are only available if you provided an IoTHub service connection string in your ux4iot deployment parameters.
Direct Method
We use the IoTHub parameters that you will need to send in the direct method request:
When authorized and grants are set, ux4iot will send a request to IoTHub to execute the requested direct method. We forward the HTTP response codes from the IoTHub.
// telemetryKey provided
{
deviceId: string;
data: {
[telemetryKey]: any;
}
timestamp: string; // iso date
}
// telemetryKey not provided
{
deviceId: string;
data: {
[telemetryKey]: {
value: any;
timestamp: string; // iso date
}
}
timestamp: '';
}
// telemetryKey provided
{
deviceId: string;
data: {
[telemetryKey]: any;
}
timestamp: string; // iso date
}
// telemetryKey not provided
{
deviceId: string;
data: {
[telemetryKey]: {
value: any;
timestamp: string; // iso date
}
}
timestamp: '';
}
{
deviceId,
data: DeviceTwin
timestamp: string // iso date
}
{
deviceId,
data: DeviceTwin
timestamp: string // iso date
}
type DirectMethodRequestBody = {
deviceId: string;
methodParams: {
// The name of the method to call on the device.
methodName: string;
// The method payload that will be sent to the device.
payload?: any;
// The maximum time a device should take to respond to the method.
responseTimeoutInSeconds?: number;
// The maximum time the service should try to connect to the device before declaring the device is unreachable.
connectTimeoutInSeconds?: number;
}
}
{
"status" : 201,
"payload" : {...}
}
type PatchDesiredPropertiesRequestBody = {
deviceId: string;
desiredPropertyPatch: Record<string, any>
}
