IoT Hub REST
The REST APIs for IoT Hub offer programmatic access to the device, messaging, and job services, and the resource provider, in IoT Hub. You can access messaging services from within an IoT service running in Azure, or directly over the Internet from any application that can send an HTTPS request and receive an HTTPS response.
Service
- Use this API to manage IoT Hub device twins. You can retrieve and update device twin properties and invoke direct methods on devices.
- Use these APIs to manage device identities in the identity registry of an IoT hub.
- Use these APIs to manage Jobs in IoT Hub. You can schedule, cancel, or get a job.
All task operations conform to the HTTP/1.1 protocol specification and each operation returns an x-ms-request-id
header that can be used to obtain information about the request. You must make sure that requests made to these resources are secure. For more information, see IoT Hub Developer Guide – Security for the specifics on how to create security tokens.
Device Messaging
Use these APIs from a device to send device-to-cloud messages to an IoT hub, and receive cloud-to-device messages from an IoT hub. All task operations conform to the HTTP/1.1 protocol specification. You must make sure that requests made to these resources are secure. For more information, see IoT Hub Developer Guide - Security for specific information about how to create security tokens.
Resource Provider
Use these APIs to manage the deployment of your IoT Hub resources. For information about how to secure these requests, see Azure REST API Reference.
Common parameters and headers
The following information is common to all tasks related to IoT Hub:
Replace
{api-version}
with "2018-06-30" in the URI.Replace
{subscription-id}
with your subscription identifier in the URI.Replace
{resourceGroupName}
with the resource group name that contains your IoT hub.Replace
{IoTHubName}
with the name of your IoT hub.Set the Content-Type header to application/json.
Set the Authorization header to a SAS token created as specified in the security tokens section of Using IoT Hub security tokens.
The Etag header is returned in all requests scoped to a single device identity, as per RFC7232.
All PUT/PATCH operations require the following headers to be specified:
If-Match = [*|<etag from get>]
DELETE operations may include the following header:
If-Match = [*|<etag from get>]
The behavior for ETags is hown in the following tables:
PUT | Resource doesn't exist | Resource exists |
---|---|---|
If-Match = "" / absent | 201 Created | 200 OK |
If-Match = "*" | 412 Precondition Failed | 200 OK |
If-Match = "xyz" | 412 Precondition Failed | 200 OK / 412 Precondition Failed |
If-None-Match = "*" | 201 Created | 412 Precondition Failed |
DELETE | Resource doesn't exist | Resource exists |
---|---|---|
If-Match = "" / absent | 204 No Content | 200 OK |
If-Match = "*" | 204 No Content | 200 OK |
If-Match = "xyz" | 204 No Content | 200 OK / 412 Precondition Failed |
For asynchronous calls:
PUT responds with 201 Created with Azure-AsyncOperation header for any operations that are asynchronous. All synchronous (updates) operations return 200 OK.
DELETE returns 202 Accepted with Location and Retry-After headers and Azure-AsyncOperation header for resources that exists.
Location header contains URL for the operation result
Retry-After header contains appropriate retry interval in seconds
Azure-AsyncOperation header contains URL for the Async operation result status
On completion, the GET to the operation result URL generates exactly the same result as if the original operation completed synchronously