Introduction

The HTTP bridge is a feature of the Gear Studio platform that allows device integration using the HTTP API through MQTT. This makes it possible to migrate devices that use the HTTP interface to use MQTT instead, with minimal changes.

Important: The HTTP bridge is primarily designed for migrating devices from HTTP to MQTT, but for new devices, it is recommended to use flexible data exchange, which can be found here. Flexible data exchange allows representing data with much more flexibility, and generally in a more compact form.

Requests

To send a request through the HTTP bridge, the following topic structure must be used:

{client-secure-id}/HttpApi/DeviceIntegration

Where client-secure-id is the username used in the connection. The topic structure includes the user ID as the first element, since each user only has permission for topics that start with that ID.

Each request must contain a JSON message, whose structure depends on the message type. However, some fields are common to all message types:

accessToken: this field indicates the access token that must be used to authenticate and authorize the request.
mqttMethod: this field indicates the request type. For example, to report a temperature value, the value "UpdateTemperatureSensorStatus" is used.
mqttRID: this is an optional field that can take any value, typically chosen at random. If this field is provided, the platform will automatically generate a response to the sent command and include the same mqttRID in that response, allowing the client to link the response with the original request.

Optionally, a response subtopic can be specified by concatenating a slash and a value at the beginning of the mqttRID. That is, {subtopic}/{random value} For example, using the subtopic /device1 and the RID 1238j9. The complete mqttRID would be device1/1238j9

Simple and Multiple Requests

Simple Requests

Simple requests allow sending a single piece of data at a time to the platform. They are generally used to report the status of a single endpoint.

Simple request example:

{
	"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"endpointID": 1,
	"temperatureCelsius": 25,
	"timestamp": "2021-02-23T14:55:03",
	"mqttMethod": "UpdateTemperatureSensorStatus",
	"mqttRID": "RXmp123"
}

Multiple Requests (Arrays)

Multiple requests allow sending several pieces of data in a single MQTT message. JSON array syntax is used, with brackets at the beginning and end, containing the data separated by commas. Multiple requests are normally used to report the status of multiple endpoints in a single message. They are also useful for a device to send data that was stored during a period without communication. In any case, the data can include different endpoints from the same device, or even endpoints from different devices.

Multiple request example:

[
	{
		"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
		"endpointID": 1,
		"temperatureCelsius": 25,
		"timestamp": "2021-02-23T14:55:03",
		"mqttMethod": "UpdateTemperatureSensorStatus",
		"mqttRID": "RXmp123"
	},
	{
		"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
		"endpointID": 2,
		"humidityPercentage": 30,
		"timestamp": "2021-02-23T15:55:03",
		"mqttMethod": "UpdateHumiditySensorStatus",
		"mqttRID": "xQzt395"
	}
]

Responses

If a value is provided in the mqttRID field, the platform will create a response message in the topic

{client-secure-id}/HttpApi/DeviceIntegrationResponse

If a subtopic is concatenated at the beginning of the mqttRID, it will be appended to the response topic:

{client-secure-id}/HttpApi/DeviceIntegrationResponse/{subtopic}

This allows knowing the final status of the request and optionally obtaining response information if the command requires it.

The response payload typically has the following format:

{
    "mqttRID":"RXmp123",
    "mqttStatus":200,
    "mqttData":"{}"
}

Name	Description	Type
mqttRID	Unique identifier for each request	string
mqttStatus	Returns the server status code (200, 500, 400, etc). If the request executed successfully, it will be 200. In case of error, it can return any code (400 or 500)	integer
mqttData	The body of the server response. It is a string containing JSON.	string