Calling API

Once an MQTT connection is established, you can call the API.

Use the PUBLISH command to send and receive requests and responses when you call the API via MQTT. See Mapping MQTT and HTTPS in the Function Guide for an example of API call with the PUBLISH command.

This topic describes how to convert HTTPS format to that of MQTT. The Thing Interaction Framework (Thing-IF) API reference and REST API Guide assume API call in HTTPS. When you use the MQTT protocol, convert requests and responses according to the following rules.

This topic explains such conversion using an example of the API call for state registration. The same rules apply to the other API calls.

Request

Send the PUBLISH command from the client to send a request via the MQTT protocol.

The command to register a state in the REST API Guide is as below. Let us convert this API to a PUBLISH command.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/states" \
  -d '{"power":true, "presetTemperature":25, "fanspeed":5, "currentTemperature":28, "currentHumidity":65}'

MQTT Topic

Specify the function to call by following the hierarchy of the MQTT topic names. The destination MQTT topic of the PUBLISH command corresponds to the HTTPS URL of the REST API. Append the part of the HTTPS URL path after /{APP_ID}/ to the MQTT topic name p/{CLIENT_ID}/thing-if/apps/{APP_ID}/.

Replace the {CLIENT_ID} with the value of the Client identifier ("mqttTopic" in the onboarding response) which was specified in the CONNECT command.

The below is the destination MQTT topic converted from the URL in the curl command in the above example of state registration.

p/{CLIENT_ID}/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/states

Payload

Specify the HTTP verb, the HTTP headers, an empty line, and the HTTP body of the API to call in the payload. Format the payload in text format with CRLF as the end-of-line character.

Follow the conversion rules as below.

  • Specify the HTTP verb in the first line. Use one of GET, HEAD, POST, PUT, PATCH, or DELETE according to the syntax of the API to call.

  • Specify the HTTP headers in the second and subsequent lines. Convert the headers instructed in sample code or the REST API Guide by following the below rules.

    • Omit the X-Kii-AppID and X-Kii-AppKey headers. The connection is aware of the target application.

    • These headers below are ignored even you specify them.

      Access-Control-Request-Method, Access-Control-Request-Headers, Connection, Content-Length, Expect, Host, Max-Forwards, Origin, Proxy-Authorization, TE, Transfer-Encoding, Upgrade, and Via

    • You can pair a request and a response by assigning a unique {REQUEST_ID} as the X-Kii-RequestID header to the request. The same X-Kii-RequestID header will be included in the PUBLISH command from the server side which contains the API response.

    • The maximum payload is 1 MB for API requests in Kii Cloud environment. If any larger payload is sent as a command request, the MQTT broker will disconnect the connection. The payload size for responses is unlimited.

  • Insert an empty line between the HTTP headers and body.

  • Specify the HTTP body in the end.

The payload below is converted from the curl command for state registration above by following these rules.

PUT
Authorization: Bearer {ACCESS_TOKEN}
X-Kii-RequestID: {REQUEST_ID}
Content-Type: application/json

{"power":true, "presetTemperature":25, "fanspeed":5, "currentTemperature":28, "currentHumidity":65}

See below to understand how specifically the curl command is converted.

  • PUT is specified as the HTTP verb.

  • Two HTTP headers in the sample code of the curl command are specified and then the X-Kii-RequestID header is added.

  • The HTTP body same as that in the sample code is specified.

Response

The PUBLISH command from the server side contains the server response.

MQTT Topic

The response PUBLISH command contains the MQTT topic name specified in the request PUBLISH command.

Ensure to check the MQTT topic name on receiving the PUBLISH command from the server because the PUBLISH command is used for various purposes. Also, ignore PUBLISH commands with unknown MQTT topic names for future enhancement.

Payload

The payload contains the result of the API execution. It has the HTTP status code, HTTP headers, an empty line, and the HTTP body. The end-of-line character is CRLF and the format is text.

The payload of the PUBLISH command below is a result example of state registration. This example does not contain any HTTP body.

204
Accept-Ranges:bytes
Age:0
Cache-Control:max-age=0, no-cache, no-store
Date:Fri, 27 May 2016 05:44:18 GMT
Connection:keep-alive
X-Kii-RequestID:{REQUEST_ID}

See the payload example with the HTTP body below. This is a response to a request to get the state.

200
Accept-Ranges:bytes
Age:0
Cache-Control:max-age=0, no-cache, no-store
Content-Type:application/json
Date:Tue, 31 May 2016 04:59:52 GMT
Connection:keep-alive
X-Kii-RequestID:{REQUEST_ID}

{
  "power" : true,
  "presetTemperature" : 25,
  "fanspeed" : 5,
  "currentTemperature" : 28,
  "currentHumidity" : 65
}

Map the payload to the HTTPS response of the REST API as below.

  • The first line contains the HTTPS status code which would be returned by the REST API such as 2xx for success and 4xx for client error. See the section for each API in the Thing Interaction Framework (Thing-IF) API reference for more information about the status code.

  • The second and subsequent lines contain HTTP headers.

    • These headers below, which would be returned by HTTPS responses of the REST API, are not returned in the MQTT protocol.

      Access-Control-Allow-Origin, Access-Control-Allow-Credentials, Access-Control-Expose-Headers, Access-Control-Max-Age, Access-Control-Allow-Methods, Access-Control-Allow-Headers, Content-Length, Server, Trailer, Transfer-Encoding, Upgrade, and Via

    • The X-Kii-RequestID header indicates the {REQUEST_ID} specified in the request. You can pair the response with the request which has the same ID.

  • The payload has an empty line between the HTTP headers and body.

  • The last part is the HTTP body.

Responses with no HTTP body do not have any data after the empty line.