HTTP Adapter

The HTTP protocol adapter exposes HTTP based endpoints for Bosch IoT Hub’s Telemetry, Event and Command&Control APIs.

The HTTP adapter requires clients to authenticate during connection establishment. The adapter supports both username/password based authentication as well as client certificate based authentication as part of a TLS handshake for that purpose.

In order to do so, clients need to provide a username and a password in the header of the message or a client certificate. The username must have the format auth-id@tenant-id.

The server certificate of Bosch IoT Hub is issued by Let’s Encrypt. Some devices directly trust Let’s Encrypt root certificate, in such case the download of server certificate is not necessary. If that is not the case, you need to import Let’s Encrypt certificate of Bosch IoT Hub in your trust store to establish TLS connection to HTTP adapter. Certificate can be downloaded as follows:

curl -o iothub.crt https://docs.bosch-iot-hub.com/cert/iothub.crt

For the examples below the command line tool curl is used. To send data to HTTP adapter also the following page can be used Bosch IoT Hub HTTP Adapter.

Communication Patterns

Publishing Telemetry Data

The HTTP adapter supports publishing of telemetry data by means of request with method POST for devices and PUT for gateways using QoS 1 or QoS 0.

Publishing Events

The HTTP adapter supports publishing of events by means of request with method POST for devices and PUT for gateways using QoS 1 only. The adapter will send a status code to the client once the event has been accepted for processing.

Command and Control

The HTTP adapter supports receiving commands by means of request with method POST for devices and PUT for gateways. The responses to the commands are sent using only QoS 1.

All above mentioned communication patterns can be used by devices connecting directly to HTTP protocol adapter or by gateways connecting to HTTP protocol adapter and acting on behalf of the actual devices. See Gateway Mode for a more detailed description.

Devices connected directly to HTTP Adapter

Publish Telemetry Data

  • URI: /telemetry
  • Method: POST
  • Request Headers:
    • (optional) authorization: The device’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the device to present a client certificate as part of the TLS handshake during connection establishment.
    • (required) content-type: The type of payload contained in the request body.
    • (optional) hono-ttd: The number of seconds the device will wait for the response.
    • (optional) qos-level: The QoS level for publishing telemetry messages. The adapter supports at most once (0) and at least once (1) QoS levels. The default value of 0 is assumed if this header is omitted.
  • Request Body:

    • (required) Arbitrary payload encoded according to the given content type.
  • Response Headers:
    • (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data.
    • (optional) hono-command: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device.
    • (optional) hono-cmd-req-id: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device.
    • (optional) hono-cmd-target-device: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device and if the response goes to a gateway that acts on behalf of the target device.
  • Response Body:
    • (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200.
    • (optional) Error details, if status code is >= 400.
  • Status Codes:
    • 200 (OK): The telemetry data has been accepted for processing. The response contains a command for the device to execute.
    • 202 (Accepted): The telemetry data has been accepted for processing. Note that if the qos-level request header is omitted (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer. However, if the QoS level header is set to 1 (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code.
    • 400 (Bad Request): The request cannot be processed. Possible reasons for this include:
      • The content type header is missing.
      • The request body is empty.
      • The QoS header value is invalid.
    • 401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.
    • 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
      • The given tenant is not allowed to use this protocol adapter.
    • 404 (Not Found): The request cannot be processed because the device is disabled or does not exist.
    • 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.
    • 503 (Service Unavailable): The request cannot be processed because there is no consumer of telemetry data for the given tenant connected to Bosch IoT Hub.

If the hono-ttd header is set in order to receive a command and if the authenticated device is actually a gateway, the returned command will be the first command that the northbound application has sent to either the gateway itself or to any device that has last sent a telemetry or event message via this gateway.

Example

Publish some JSON data for device:

curl -i -u auth-id@tenant-id:password -H 'content-type: application/json' --data-binary '{"temp": 5}' https://http.bosch-iot-hub.com/telemetry

HTTP/1.1 202 Accepted
content-length: 0

Publish Events

  • URI: /event
  • Method: POST
  • Request Headers:
    • (optional) authorization: The device’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the device to present a client certificate as part of the TLS handshake during connection establishment.
    • (required) content-type: The type of payload contained in the request body.
    • (optional) hono-ttd: The number of seconds the device will wait for the response.
    • (optional) hono-ttl: The time-to-live in number of seconds for event messages.
  • Request Body:
    • (required) Arbitrary payload encoded according to the given content type.
  • Response Headers:
    • (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data.
    • (optional) hono-command: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device.
    • (optional) hono-cmd-req-id: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device.
    • (optional) hono-cmd-target-device: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device and if the response goes to a gateway that acts on behalf of the target device.
  • Response Body:
    • (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200.
    • (optional) Error details, if status code is >= 400.
  • Status Codes:
    • 200 (OK): The event has been accepted for processing. The response contains a command for the device to execute.
    • 202 (Accepted): The event has been accepted for processing.
    • 400 (Bad Request): The request cannot be processed. Possible reasons for this include:
      • The content type header is missing.
      • The request body is empty but the event is not of type empty-notification.
    • 401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.
    • 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
      • The given tenant is not allowed to use this protocol adapter.
    • 404 (Not Found): The request cannot be processed because the device is disabled or does not exist.
    • 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.
    • 503 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Bosch IoT Hub.

If the hono-ttd header is set in order to receive a command and if the authenticated device is actually a gateway, the returned command will be the first command that the application has sent to either the gateway itself or to any device that has last sent a telemetry or event message via this gateway.

Example

Publish some JSON data for device:

curl -i -u auth-id@tenant-id:password:hono-secret -H 'content-type: application/json' --data-binary '{"alarm": true}' https://http.bosch-iot-hub.com/event

HTTP/1.1 202 Accepted
content-length: 0

Sending a Response to a Command

After a connected business application sent command to a connected device, the device may send a response to this command.

  • URI: /command/res/${commandRequestId} or /command/res/${commandRequestId}?hono-cmd-status=${status}
  • Method: POST
  • Request Headers:
    • (optional) authorization: The device’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the device to present a client certificate as part of the TLS handshake during connection establishment.
    • (optional) content-type: A media type describing the semantics and format of the payload contained in the request body. This header may be set if the result of processing the command on the device is non-empty. In this case the result data is contained in the request body.
    • (optional) hono-cmd-status: The status of the command execution. If not set, the adapter expects that the URI contains it as request parameter at the end.
  • Request Body:
    • (optional) Arbitrary data representing the result of processing the command on the device.
  • Status Codes:
    • 202 (Accepted): The response has been successfully delivered to the application that has sent the command.
    • 400 (Bad Request): The request cannot be processed because the command status is missing.
    • 401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.
    • 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
      • The given tenant is not allowed to use this protocol adapter.
    • 404 (Not Found): The request cannot be processed because the device is disabled or does not exist.
    • 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.
    • 503 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
      • There is no application listening for a reply to the given commandRequestId.
      • The application has already given up on waiting for a response.

Example

Send a response to a previously received command with the command-request-id req-id-uuid for device 4711:

curl -i -u auth-id@tenant-id:password -H 'content-type: application/json' --data-binary '{"brightness-changed": true}' https://http.bosch-iot-hub.com/command/res/req-id-uuid?hono-cmd-status=200

HTTP/1.1 202 Accepted
content-length: 0

Devices connected via gateway to HTTP Adapter

Gateways publish data on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.

Publish Telemetry Data

  • URI: /telemetry/${tenantId}/${deviceId}
  • Method: PUT
  • Request Headers:
    • (optional) authorization: The gateway’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the gateway to present a client certificate as part of the TLS handshake during connection establishment.
    • (required) content-type: The type of payload contained in the request body.
    • (optional) hono-ttd: The number of seconds the device will wait for the response.
    • (optional) qos-level: The QoS level for publishing telemetry messages. The adapter supports at most once (0) and at least once (1) QoS levels. The default value of 0 is assumed if this header is omitted.
  • Request Body:
    • (required) Arbitrary payload encoded according to the given content type.
  • Response Headers:
    • (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data.
    • (optional) hono-command: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device.
    • (optional) hono-cmd-req-id: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device.
    • (optional) hono-cmd-target-device: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device.
  • Response Body:
    • (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200.
    • (optional) Error details, if status code is >= 400.
  • Status Codes:
    • 200 (OK): The telemetry data has been accepted for processing. The response contains a command for the device to execute.
    • 202 (Accepted): The telemetry data has been accepted for processing. Note that if the qos-level request header is omitted (at most once semantics), this status code does not mean that the message has been delivered to any potential consumer. However, if the QoS level header is set to 1 (at least once semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with this status code.
    • 400 (Bad Request): The request cannot be processed. Possible reasons for this include:
      • The content type header is missing.
      • The request body is empty.
      • The QoS header value is invalid.
    • 401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.
    • 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
      • The tenant that the gateway belongs to is not allowed to use this protocol adapter.
      • The device belongs to another tenant than the gateway.
      • The gateway is not authorized to act on behalf of the device.
      • The gateway associated with the device is not registered or disabled.
    • 404 (Not Found): The request cannot be processed because the device is disabled or does not exist.
    • 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.
    • 503 (Service Unavailable): The request cannot be processed because there is no consumer of telemetry data for the given tenant connected to Bosch IoT Hub.

Example

Publish some JSON data for device 4712:

curl -i -X PUT -u gw-auth-id@tenant-id:gw-password -H 'content-type: application/json' --data-binary '{"temp": 5}' https://http.bosch-iot-hub.com/telemetry/tenant-id/4712

HTTP/1.1 202 Accepted
content-length: 0

Publish Events

  • URI: /event/${tenantId}/${deviceId}
  • Method: PUT
  • Request Headers:
    • (optional) authorization: The gateway’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the gateway to present a client certificate as part of the TLS handshake during connection establishment.
    • (required) content-type: The type of payload contained in the request body.
    • (optional) hono-ttd: The number of seconds the device will wait for the response.
    • (optional) hono-ttl: The time-to-live in number of seconds for event messages.
  • Request Body:
    • (required) Arbitrary payload encoded according to the given content type.
  • Response Headers:
    • (optional) content-type: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data.
    • (optional) hono-command: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device.
    • (optional) hono-cmd-req-id: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device.
    • (optional) hono-cmd-target-device: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device.
  • Response Body:
    • (optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200.
    • (optional) Error details, if status code is >= 400.
  • Status Codes:
    • 200 (OK): The event has been accepted and put to a persistent store for delivery to consumers. The response contains a command for the device to execute.
    • 202 (Accepted): The event has been accepted and put to a persistent store for delivery to consumers.
    • 400 (Bad Request): The request cannot be processed. Possible reasons for this include:
      • The content type header is missing.
      • The request body is empty but the event is not of type empty-notification.
    • 401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.
    • 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
      • The tenant that the gateway belongs to is not allowed to use this protocol adapter.
      • The device belongs to another tenant than the gateway.
      • The gateway is not authorized to act on behalf of the device.
      • The gateway associated with the device is not registered or disabled.
    • 404 (Not Found): The request cannot be processed because the device is disabled or does not exist.
    • 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.
    • 503 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Bosch IoT Hub.

Example

Publish some JSON data for device 4712:

curl -i -X PUT -u gw-auth-id@tenant-id:gw-password -H 'content-type: application/json' --data-binary '{"temp": 5}' https://http.bosch-iot-hub.com/event/tenant-id/4712

HTTP/1.1 202 Accepted
content-length: 0

Sending a Response to a Command

After a connected business application sent command to a device connected via a gateway, the device may send a response to this command via the gateway.

  • URI: /command/res/${tenantId}/${deviceId}/${commandRequestId} or /command/res/${tenantId}/${deviceId}/${commandRequestId}?hono-cmd-status=${status}
  • Method: PUT
  • Request Headers:
    • (optional) authorization: The gateway’s auth-id and plain text password encoded according to the Basic HTTP authentication scheme. If not set, the adapter expects the gateway to present a client certificate as part of the TLS handshake during connection establishment.
    • (optional) content-type: A media type describing the semantics and format of the payload contained in the request body (the outcome of processing the command).
    • (optional) hono-cmd-status: The status of the command execution. If not set, the adapter expects that the URI contains it as request parameter at the end.
  • Request Body:
    • (optional) Arbitrary data representing the result of processing the command on the device.
  • Status Codes:
    • 202 (Accepted): The response has been successfully delivered to the application that has sent the command.
    • 400 (Bad Request): The request cannot be processed because the command status is missing.
    • 403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this might be:
      • The given tenant is not allowed to use this protocol adapter.
      • The given device does not belong to the given tenant.
      • The gateway is not authorized to act on behalf of the device.
      • The gateway associated with the device is not registered or disabled.
    • 404 (Not Found): The request cannot be processed because the device is disabled or does not exist.
    • 429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.
    • 503 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
      • There is no application listening for a reply to the given commandRequestId.
      • The application has already given up on waiting for a response.

Example

Send a response to a previously received command with the command-request-id req-id-uuid for device 4712:

curl -i -X PUT -u gw-auth-id@tenant-id:gw-password -H 'content-type: application/json' --data-binary '{"brightness-changed": true}' https://http.bosch-iot-hub.com/command/res/tenant-id/4712/req-id-uuid?hono-cmd-status=200

HTTP/1.1 202 Accepted
content-length: 0

Specifying the Time a Device will wait for a Response

The HTTP adapter lets devices indicate the number of seconds they will wait for a response by setting a header or a query parameter.

Using HTTP Header

The (optional) hono-ttd header can be set in requests for publishing telemetry data or events.

Example

curl -i -u auth-id@tenant-id:password -H 'content-type: application/json' -H 'hono-ttd: 60' --data-binary '{"temp": 5}' https://http.bosch-iot-hub.com/telemetry

HTTP/1.1 202 Accepted
content-length: 0

Using a Query Parameter

Alternatively the hono-ttd query parameter can be used:

curl -i -u auth-id@tenant-id:password -H 'content-type: application/json' --data-binary '{"temp": 5}' https://http.bosch-iot-hub.com/telemetry?hono-ttd=60

HTTP/1.1 202 Accepted
content-length: 0