Skip to content

Connecting to the API

Once you have the required tokens, you can connect to the Messaging API. This page describes the configuration for each API.

Note

For the Messaging API, MQTT and HTTP serve different purposes. See MQTT and HTTP for more information.

Client ID

When your external client establishes a connection with one of the APIs, it can pass a client ID to the DSH. It’s strongly recommended to use the value of the “client-id” key in the MQTT token as the client ID:

  • In the MQTT protocol specification, each external MQTT client that sets up a connection with an MQTT broker (this is the Messaging API of the DSH) must have a unique external MQTT client identifier, the client ID. The connecting external MQTT client must pass its chosen client ID in the initial CONNECT message, or can ignore it and let the broker assign a client ID.
  • However, the DSH exposes the Messaging API both via MQTT and HTTP, and it needs to ensure that the client ID of each external client is unique across the two protocols.
  • For that reason, the DSH uses the value of the “client-id” key in the MQTT token, and it ignores the client ID that is passed by or created for MQTT clients at connection time.
  • Even still, it’s good practice to be consistent across the board, and to pass the value of the token’s “client-id” key to the broker when establishing a connection.

Note

The DSH allows only 1 live connection for each client ID. If you establish a connection with a specific client ID, then the DSH will terminate any existing connection that already uses this client ID.

MQTT

In order to connect to Messaging API via MQTT, you need to extract the following information from the MQTT token:

  • The endpoint
  • The client ID
  • The TCP ports

See Contents of MQTT token for more information.

Take the following guidelines into account:

  • Always use TLS. The platform doesn’t support unsecured connections.
  • Use a unique MQTT client ID. It’s strongly recommended to use the “client-id” key from the MQTT token.
  • You can use a random MQTT username, because the Messaging API ignores this field.
  • Use the MQTT token as the MQTT password.

To connect over MQTTS (MQTT over SSL), connect to the endpoint on the port specified for MQTTS, and configure the MQTT client to use TLS.

To connect over WebSockets, use one of the following URLs defined in the “ports” key of the MQTT token. See Contents of MQTT token for more information.

HTTP

In order to connect to the Messaging API via HTTP, you need the following information:

  • The URLs have the structure https://api.<platform-url>/data/v0/<single|multi>/<mqtt-topic>.
  • Always use TLS. The platform doesn’t support unsecured connections.
  • Each time an external client wakes up, it can set up an HTTPS connection using an MQTT token in the Authorization: Bearer HTTP header of the request.

Tip

See HTTP specification for more information.