@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api iotHubClient
@base https://management.azure.com
@version 2019-07-01-preview
@auth OAuth2
@common_fields {api-version: any # The version of the API., subscriptionId: any # The subscription identifier.}
@endpoints 32
@hint download_for_search
@toc providers(1), subscriptions(31)

@group providers
@endpoint GET /providers/Microsoft.Devices/operations
@desc Lists all of the available IoT Hub REST API operations.
@returns(200) OK. The request has succeeded.

@endgroup

@group subscriptions
@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}
@desc Get the non-security related metadata of an IoT hub
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub.}
@returns(200) The body contains all the non-security properties of the IoT hub. Security-related properties are set to null.

@endpoint PUT /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}
@desc Create or update the metadata of an IoT hub.
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., iotHubDescription: map # The IoT hub metadata and security metadata.}
@optional {If-Match: any # ETag of the IoT Hub. Do not specify for creating a brand new IoT Hub. Required to update an existing IoT Hub.}
@returns(200) This is returned as a response to the status polling request for the create or update operation. The body contains the resource representation that indicates a transitional provisioning state.
@returns(201) This is a long running operation. The operation returns a 201 if the validation is complete. The response includes an Azure-AsyncOperation header that contains a status URL. Clients are expected to poll the status URL for the status of the operation. If successful, the operation returns HTTP status code of 201 (OK).

@endpoint PATCH /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}
@desc Update an existing IoT Hubs tags.
@required {resourceGroupName: any # Resource group identifier., resourceName: any # Name of iot hub to update., IotHubTags: any # Updated tag information to set into the iot hub instance.}
@returns(200) Iot Hub was successfully updated

@endpoint DELETE /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}
@desc Delete an IoT hub
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub.}
@returns(200) This is returned as a response to the status polling request for the delete operation. The body contains the resource representation that indicates a transitional provisioning state.
@returns(202) The Iot Hub resource provider always returns a 202 Accepted status code with valid Location and Retry-After headers. The resource provider also sets the Azure-AsyncOperation header with a URL that points to the operation resource for this operation. Subsequent GET attempts on the resource after a DELETE operation return a resource representation that indicates a transitional provisioning state (such as Terminating). To retrieve the status of the operation, a client can either poll the URL returned in the Location header after the Retry-After interval, get the IoT Hub service status directly, or query the operation resource.
@returns(204) Once the long running delete operation completes successfully, a 204 No Content status code is returned when the status polling request finds the Iot hub metadata in the service and the status of the delete operation is set to a completed state.
@errors {404: After the long running delete operation completes successfully, a 404 Not Found is returned when the status polling request no longer finds the Iot hub metadata in the service.}

@endpoint GET /subscriptions/{subscriptionId}/providers/Microsoft.Devices/IotHubs
@desc Get all the IoT hubs in a subscription
@returns(200) This is a synchronous operation. The body contains a JSON-serialized array of the metadata from all the IoT hubs in the subscription.

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs
@desc Get all the IoT hubs in a resource group
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub.}
@returns(200) This is a synchronous operation. The body contains a JSON-serialized array of the metadata from all the IoT hubs in the resource group.

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/IotHubStats
@desc Get the statistics from an IoT hub
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub.}
@returns(200) This is a synchronous operation. The body contains JSON-serialized statistics from the identity registry in the IoT hub.

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/skus
@desc Get the list of valid SKUs for an IoT hub
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub.}
@returns(200) This is a synchronous operation. The body contains a JSON-serialized array of the valid SKUs for this IoT hub.

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/eventHubEndpoints/{eventHubEndpointName}/ConsumerGroups
@desc Get a list of the consumer groups in the Event Hub-compatible device-to-cloud endpoint in an IoT hub
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., eventHubEndpointName: any # The name of the Event Hub-compatible endpoint.}
@returns(200) This is a synchronous operation. The body contains a JSON-serialized list of the consumer groups in the Event Hub-compatible endpoint in this IoT hub

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/eventHubEndpoints/{eventHubEndpointName}/ConsumerGroups/{name}
@desc Get a consumer group from the Event Hub-compatible device-to-cloud endpoint for an IoT hub
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., eventHubEndpointName: any # The name of the Event Hub-compatible endpoint in the IoT hub., name: any # The name of the consumer group to retrieve.}
@returns(200) This is a synchronous operation. The body contains a JSON-serialized consumer group.

@endpoint PUT /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/eventHubEndpoints/{eventHubEndpointName}/ConsumerGroups/{name}
@desc Add a consumer group to an Event Hub-compatible endpoint in an IoT hub
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., eventHubEndpointName: any # The name of the Event Hub-compatible endpoint in the IoT hub., name: any # The name of the consumer group to add.}
@returns(200) This is a synchronous operation.

@endpoint DELETE /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/eventHubEndpoints/{eventHubEndpointName}/ConsumerGroups/{name}
@desc Delete a consumer group from an Event Hub-compatible endpoint in an IoT hub
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., eventHubEndpointName: any # The name of the Event Hub-compatible endpoint in the IoT hub., name: any # The name of the consumer group to delete.}
@returns(200) This is a synchronous operation.

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/jobs
@desc Get a list of all the jobs in an IoT hub. For more information, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub.}
@returns(200) This is a synchronous operation. The response contains a JSON-serialized array of all the jobs in the IoT hub.

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/jobs/{jobId}
@desc Get the details of a job from an IoT hub. For more information, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., jobId: any # The job identifier.}
@returns(200) This is a synchronous operation. The response contains a JSON-serialized description of the job in the IoT hub.

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/quotaMetrics
@desc Get the quota metrics for an IoT hub
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub.}
@returns(200) This is a synchronous operation. The response contains a JSON-serialized array of the quota metrics for the IoT hub.

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/routingEndpointsHealth
@desc Get the health for routing endpoints
@required {resourceGroupName: any, iotHubName: any}
@returns(200) OK

@endpoint POST /subscriptions/{subscriptionId}/providers/Microsoft.Devices/checkNameAvailability
@desc Check if an IoT hub name is available
@required {operationInputs: map # Set the name parameter in the OperationInputs structure to the name of the IoT hub to check.}
@returns(200) This is a synchronous operation. The body contains a JSON-serialized response that specifies whether the IoT hub name is available. If the name is not available, the body contains the reason.

@endpoint GET /subscriptions/{subscriptionId}/providers/Microsoft.Devices/usages
@desc Get the number of iot hubs in the subscription
@returns(200) OK

@endpoint POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/routing/routes/$testall
@desc Test all routes
@required {input: map # Input for testing all routes, iotHubName: any # IotHub to be tested, resourceGroupName: any # resource group which Iot Hub belongs to}
@returns(200) OK

@endpoint POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/routing/routes/$testnew
@desc Test the new route
@required {input: map # Route that needs to be tested, iotHubName: any # IotHub to be tested, resourceGroupName: any # resource group which Iot Hub belongs to}
@returns(200) OK

@endpoint POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/listkeys
@desc Get the security metadata for an IoT hub. For more information, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-security
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub.}
@returns(200) This is a synchronous operation. The body contains a JSON-serialized array of shared access policies, including keys, that you can use to access the IoT hub endpoints.

@endpoint POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/IotHubKeys/{keyName}/listkeys
@desc Get a shared access policy by name from an IoT hub. For more information, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-security
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., keyName: any # The name of the shared access policy.}
@returns(200) This is a synchronous operation. The body contains a JSON-serialized shared access policy, including keys, that you can use to access one or more IoT hub endpoints.

@endpoint POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/exportDevices
@desc Exports all the device identities in the IoT hub identity registry to an Azure Storage blob container. For more information, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., exportDevicesParameters: map # The parameters that specify the export devices operation.}
@returns(200) OK

@endpoint POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/importDevices
@desc Import, update, or delete device identities in the IoT hub identity registry from a blob. For more information, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., importDevicesParameters: map # The parameters that specify the import devices operation.}
@returns(200) OK

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates
@desc Get the certificate list.
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub.}
@returns(200) The body contains all the certificate list.

@endpoint GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}
@desc Get the certificate.
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., certificateName: any # The name of the certificate}
@returns(200) The body contains the certificate.

@endpoint PUT /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}
@desc Upload the certificate to the IoT hub.
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., certificateName: any # The name of the certificate, certificateDescription: map # The certificate body.}
@optional {If-Match: any # ETag of the Certificate. Do not specify for creating a brand new certificate. Required to update an existing certificate.}
@returns(200) If certificate already exist and update was successful, the operation returns HTTP status code of 201 (OK).
@returns(201) If certificate didn't exist creation was successful, the operation returns HTTP status code of 201 (OK).

@endpoint DELETE /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}
@desc Delete an X509 certificate.
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., certificateName: any # The name of the certificate, If-Match: any # ETag of the Certificate.}
@returns(200) Certificate has been deleted.
@returns(204) Certificate does not exist.

@endpoint POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}/generateVerificationCode
@desc Generate verification code for proof of possession flow.
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., certificateName: any # The name of the certificate, If-Match: any # ETag of the Certificate.}
@returns(200) The body contains the certificate.

@endpoint POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}/verify
@desc Verify certificate's private key possession.
@required {resourceGroupName: any # The name of the resource group that contains the IoT hub., resourceName: any # The name of the IoT hub., certificateName: any # The name of the certificate, certificateVerificationBody: map # The name of the certificate, If-Match: any # ETag of the Certificate.}
@returns(200) The body contains the certificate.

@endpoint POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/failover
@desc Manual Failover Fail over
@required {iotHubName: any # IotHub to fail over, failoverInput: map # Region to failover to. Must be a azure DR pair, resourceGroupName: any # resource group which Iot Hub belongs to}
@returns(200) Long running Manual failover operation completed
@returns(202) Manual failover initiated

@endgroup

@end