Comment on page
REST API Reference
Ux4iot REST API
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.
get
https://ux4iot-xyz.westeurope.azurecontainer.io
/version
Get the server version of ux4iot
get
https://ux4iot-xyz.westeurope.azurecontainer.io
/status
Get the current status of ux4iot
put
https://ux4iot-xyz.westeurope.azurecontainer.io
/logLevel/:level
Set the log level of ux4iot
post
https://ux4iot-xyz.westeurope.azurecontainer.io
/session
Opens a new session in ux4iot
delete
https://ux4iot-xyz.westeurope.azurecontainer.io
/sessions/:sessionId
Delete a session by ID
delete
https://ux4iot-xyz.westeurope.azurecontainer.io
/sessions
Delete all sessions
Grants authorize a session to subscribe to resources, patch desired properties and execute direct methods.
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.
type DeviceTwinGrantRequest = { sessionId: string; deviceId: string; type: 'deviceTwin'; }
type ConnectionStateGrantRequest = { sessionId: string; deviceId: string; type: 'connectionState'; }
type D2CMessageGrantRequest = { sessionId: string; deviceId: string; type: 'd2cMessages'; }
type DesiredPropertiesGrantRequest = { sessionId: string; deviceId: string; type: 'desiredProperties'; }
type TelemetryGrantRequest = {
sessionId: string;
deviceId: string;
type: 'telemetry';
telemetryKey: string | null;
}
type DirectMethodGrantRequest = {
sessionId: string;
deviceId: string;
type: 'telemetry';
directMethodName: string | null;
}
put
https://ux4iot-xyz.westeurope.azurecontainer.io/
grants
Forward a grant
delete
https://ux4iot-xyz.westeurope.azurecontainer.io/
grants
Revoke a grant
A subscription request lets a session subscribe to live data from the EventHub. Similar to GrantRequests, there are multiple SubscriptionRequest types:
export type TelemetrySubscriptionRequest = {
sessionId: string;
deviceId: string;
type: 'telemetry';
telemetryKey: string | null;
};
export type DeviceTwinSubscriptionRequest = { sessionId: string; deviceId: string; type: 'deviceTwin'; };
export type ConnectionStateSubscriptionRequest = { sessionId: string; deviceId: string; type: 'connectionState'; };
export type D2CMessageSubscriptionRequest = { sessionId: string; deviceId: string; type: 'd2cMessages'; };
put
https://ux4iot-xyz.westeurope.azurecontainer.io
/subscription
Subscribe to live data
delete
https://ux4iot-xyz.westeurope.azurecontainer.io
/subscription
Unsubscribe from live data
put
https://ux4iot-xyz.westeurope.azurecontainer.io
/subscriptions
Bulk subscribe to multiple devices
delete
https://ux4iot-xyz.westeurope.azurecontainer.io
/subscriptions
Bulk unsubscribe from multiple devices
get
https://ux4iot-xyz.westeurope.azurecontainer.io
/lastValue/:deviceId/:telemetryKey?
Read last telemetry values for device
delete
https://ux4iot-xyz.westeurope.azurecontainer.io
/lastValue/:deviceId
Remove all last values for a device
get
https://ux4iot-xyz.westeurope.azurecontainer.io
/deviceTwin/:deviceId
Read last device twin for device
get
https://ux4iot-xyz.westeurope.azurecontainer.io
/connectionState/:deviceId
Read last connection state for device
These api resources are only available if you provided an IoTHub service connection string in your ux4iot deployment parameters.
We use the IoTHub parameters that you will need to send in the direct method request:
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;
}
}
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.
post
https://ux4iot-xyz.westeurope.azurecontainer.io
/directMethod
Executes a direct method on an IoTHub device
Apply a patch to desired properties of a device using the following request body:
type PatchDesiredPropertiesRequestBody = {
deviceId: string;
desiredPropertyPatch: Record<string, any>
}
patch
https://ux4iot-xyz.westeurope.azurecontainer.io
/deviceTwinDesiredProperties
Executes a patch of desired properties on a device twin
Last modified 2mo ago