Using API via MQTT
Follow the steps in this topic to implement the thing with the MQTT protocol only.
Use the API via MQTT to make use of the features of Thing Interaction Framework. You need to communicate via HTTPS if you need to operate your app with the user's access token or the features of the Kii Cloud SDK.
Communication Overview
Follow these steps to implement the thing with MQTT.
Onboard the thing to get information of the MQTT broker to connect
First, connect to the default MQTT broker anonymously to onboard the thing. The default MQTT broker will return the onboarding result and information about an MQTT broker which accepts your requests.
Kii Cloud has the default MQTT broker with a static URL. Access the MQTT broker anonymously to onboard the thing and then get connection information of a different MQTT broker which accepts actual requests.
Connect to the MQTT broker to call the API
Connect to the MQTT broker whose information was obtained in the previous step.
This MQTT broker accepts actual requests from the thing. Requests to handle the thing are sent over the new connection.
See the below figure for a communication example.
The PUBLISH command carries both API requests and responses. The payload of the PUBLISH command contains the detail of such requests and responses.
The below sections outline the payload. See Implementation with MQTT Only in the REST API guide for Thing-IF to learn how to specify the payload.
Mapping MQTT and HTTPS
The Kii Cloud API is designed to be used via HTTPS. To use the API via MQTT, you need to map HTTPS responses and requests to those of MQTT.
The PUBLISH command carries requests. Specify the API parameters in the PUBLISH command as below.
Specify the MQTT topic name to name the URL hierarchy of the REST API to call. See MQTT Topics below for more information.
Specify the HTTP verb such as POST and GET, HTTP headers, and the HTTP body in text format in the payload of the PUBLISH command.
Kii Cloud interprets the payload of the received PUBLISH command in HTTPS format and maps its response to a PUBLISH command to send to the client.
The MQTT client receives the PUBLISH command which contains the MQTT topic name that was specified in the request.
The payload of the PUBLISH command contains an HTTPS status code, HTTP header, and the HTTP body in text format.
Pairing Request with Response
You can pair PUBLISH commands as a set of a request and a response with a request ID specified in the payload.
When the MQTT client sends a request, it generates a request ID which is unique on the connection and specifies it as the X-Kii-RequestID header. After the API is executed, the server returns the same ID in one of HTTP headers in the response PUBLISH command. So, the client can pair the sent request and the received response.
You can generate any client-friendly string as the request ID.
MQTT Topics
When you call APIs via MQTT, there are multiple MQTT topics corresponding to the API hierarchy. Send and receive PUBLISH commands directly to and from those MQTT topics.
The figure below shows three MQTT topics corresponding to the four REST APIs listed in the Thing Interaction Framework (Thing-IF) API reference. Each MQTT topic has function(s) defined in the corresponding REST APIs as shown in the figure.
For example, the first MQTT topic in the figure can execute two functions, registering a state and getting the state, because it corresponds to the REST API /targets/thing:{targetID}/states. The HTTP verb specified in the payload of the PUBLISH command determines the function to be executed.
Using Push Notification Together
If you make use of the features of Thing Interaction Framework with things, you use push notification together with the API call via MQTT unless things only report their states to Kii Cloud. This is because things need to receive push notifications to receive commands from mobile apps.
Implement push notification as follows:
When the thing is onboarded to the default MQTT broker, an MQTT topic name is returned. Subscribe to the MQTT topic with the SUBSCRIBE command when the MQTT client connects to the MQTT broker for API call.
The PUBLISH command from the server can carry push notification. If an MQTT topic name in the PUBLISH command is the one for push notification, it means that the PUBLISH command is issued for push notification. Parse the payload as the detailed information of push notification.
See Using Push Notification via MQTT to learn how to handle push notification via the MQTT protocol.