REST API Reference
Ux4iot REST API
Last updated
Ux4iot REST API
Last updated
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
This resource can always be requested without any credentials.
GET
https://ux4iot-xyz.westeurope.azurecontainer.io/status
Helpful when you want to ensure the correct deployment of ux4iot.
PUT
https://ux4iot-xyz.westeurope.azurecontainer.io/logLevel/:level
POST
https://ux4iot-xyz.westeurope.azurecontainer.io/session
DELETE
https://ux4iot-xyz.westeurope.azurecontainer.io/sessions/:sessionId
DELETE
https://ux4iot-xyz.westeurope.azurecontainer.io/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.
PUT
https://ux4iot-xyz.westeurope.azurecontainer.io/grants
Add a grant for the sessionId
contained in the grant.
DELETE
https://ux4iot-xyz.westeurope.azurecontainer.io/grants
Revoke the grant given
A subscription request lets a session subscribe to live data from the EventHub. Similar to GrantRequests, there are multiple SubscriptionRequest types:
PUT
https://ux4iot-xyz.westeurope.azurecontainer.io/subscription
DELETE
https://ux4iot-xyz.westeurope.azurecontainer.io/subscription
PUT
https://ux4iot-xyz.westeurope.azurecontainer.io/subscriptions
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.
DELETE
https://ux4iot-xyz.westeurope.azurecontainer.io/subscriptions
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.
GET
https://ux4iot-xyz.westeurope.azurecontainer.io/lastValue/:deviceId/:telemetryKey?
This endpoint both supports requests with sessionId header or requests with Shared-Access-Key header.
If you use a sessionId, then it will be check whether a grant for the device telemetry exists before the last values are returned.
If you use a Shared-Access-Key, then any last value will be returned, without grants being checked.
DELETE
https://ux4iot-xyz.westeurope.azurecontainer.io/lastValue/:deviceId
This endpoint both supports requests with sessionId header or requests with Shared-Access-Key header.
If you use a sessionId, then it will be check whether a grant for the device telemetry exists before the last values are returned.
If you use a Shared-Access-Key, then any last value will be returned, without grants being checked.
GET
https://ux4iot-xyz.westeurope.azurecontainer.io/deviceTwin/:deviceId
Returns the last device twin for a device, if you have provided a IoTHub service connection string in your ux4iot deployment parameters.
GET
https://ux4iot-xyz.westeurope.azurecontainer.io/connectionState/:deviceId
Returns the last connection state for a device.
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.
Read more about the connection state concept here
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:
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
Provide a body containing the following
Apply a patch to desired properties of a device using the following request body:
PATCH
https://ux4iot-xyz.westeurope.azurecontainer.io/deviceTwinDesiredProperties
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|