Executing REST API

The Thing SDK Embedded supports execution of any REST APIs of Kii Cloud. By executing the REST APIs, you can use functions which are not supported by the Thing SDK Embedded.

Refer to the curl commands in REST Programming Guide and API documentation in References for parameters of the REST APIs.

This topic explains how to execute the curl command which calls the REST API from the Thing SDK Embedded to search objects.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/vnd.kii.QueryRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/VENDOR_THING_ID:{VENDOR_THING_ID}/buckets/myBucket/query" \
  -d '{
       "bucketQuery": {
         "clause": {
           "type": "range", "field": "temperature",
           "lowerLimit": 20
         },
         "orderBy": "temperature", "descending": false
       },
       "bestEffortLimit": 5
     }'

This command calls the REST API to search objects. It gets objects whose temperature field is more than or equal to 20 within the thing scope. At most 5 objects are returned in descending order in the response to one search request. See Querying KiiObjects for the details of the REST API specification.

When you decide parameter values which affect traffic such as bestEffortLimit in the above sample, consider the buffer size of the kii.kii_core.http_context specified at SDK initialization. An error occurs when the data size of the response is larger than the buffer.

Implement code like below to execute a process equivalent to the curl command from the SDK.

int ret;

#define RESOURCE_PATH "/api/apps/" EX_APP_ID "/things/VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS/buckets/myBucket/query"
#define CONTENT_TYPE "application/vnd.kii.QueryRequest+json"

/* Start to create a REST API request. */
ret = kii_api_call_start(&kii, "POST", RESOURCE_PATH, CONTENT_TYPE, KII_TRUE);
if (ret != 0) {
  /* Handle the error. */
  return;
}

/* Set HTTP headers if needed. */
/* ret = kii_api_call_append_header(&kii, "X-MY-HEADER1", "MyHeaderValue"); */
/* ret = kii_api_call_append_header(&kii, "X-MY-HEADER2", "MyHeaderValue"); */

#define HTTP_BODY "{" \
                  "  \"bucketQuery\": {" \
                  "    \"clause\": {" \
                  "      \"type\": \"range\", \"field\": \"temperature\"," \
                  "      \"lowerLimit\": 20" \
                  "    }," \
                  "    \"orderBy\": \"temperature\", \"descending\": false" \
                  "  }," \
                  "  \"bestEffortLimit\": 5" \
                  "}"

/* Append the request body. */
ret = kii_api_call_append_body(&kii, HTTP_BODY, strlen(HTTP_BODY));
if (ret != 0) {
  /* Handle the error. */
  return;
}

/* Send the created REST API request. */
ret = kii_api_call_run(&kii);
if (ret != 0) {
  /* Handle the error. */
  return;
}

printf("status:%d\n", kii.kii_core.response_code);
printf("result:%s\n", kii.kii_core.response_body);

To execute the REST API, call these APIs of Thing SDK Embedded in order.

kii_api_call_start()

Call this function to start definition of the REST API. Specify arguments as below.
- kii_t
  
  Specify the initialized kii_t structure.
  
  This example requires the thing access token to search objects. Therefore, it is assumed that the kii_t structure contains the thing access token.
- HTTP Verb
  
  Specify the HTTP verb to use in the REST API such as GET and POST. The above example uses POST based on the parameter of the curl command.
- Resource Path
  
  Specify the URL path to access the REST API. Remove the server name from the resource path used in the curl command and specify the remaining part as the resource path.
  
  Note that this sample code accesses a bucket in the thing scope of the thing whose vendorThingID is rBnvSPOXBDF9r29GJeGS. It is assumed that the kii_t structure contains the thing access token.
- Content-Type
  
  Specify the Content-Type to be used in the HTTP request of the REST API. See References if curl command samples of your interest in the REST Programming Guide do not have the Content-Type.
- Having or Not Having the Authorization Header
  
  Set KII_TRUE to use the access token from the kii_t structure in the Authorization header. Set KII_FALSE to access Kii Cloud anonymously without adding the Authorization header to the request.
kii_api_call_append_header()

Add special HTTP headers to the REST API with this function if needed. Otherwise, you do not need to call this function.
kii_api_call_append_body()

Add the HTTP body with this function. If you use the GET method, you do not need to call this function.

As arguments, specify a string or a pointer to binary data to be specified in the HTTP body and its length. You can call this function multiple times to add data but an error occurs if the data size of the entire response is larger than that specified in the kii.kii_core.http_context.

The Content-Length header is automatically set based on the length of the added HTTP body.
kii_api_call_run()

Call this function to send the request to Kii Cloud once you prepare necessary data.

The execution result of the REST API can be obtained from the kii_t structure. You can get the HTTP status code from the kii.kii_core.response_code and the HTTP body data from the kii.kii_core.response_body.

Text data of the HTTP body in the response to the search request in the sample code will follow the specification of the REST API as below. The program on the thing can use it by getting field values with the kii_json library described in Parsing JSON.

{
  "queryDescription": "WHERE ( 20 <= temperature ) ORDER BY temperature ASC",
  "results": [
    {
      "_created": 1465959304473,
      "_id": "8f7ce090-32a4-11e6-b38c-22000a7f900d",
      "_modified": 1465959304473,
      "_owner": "702b5ba64301b42bc82318ae5a0459b3",
      "_version": "1",
      "power": true,
      "status": "ECO-MODE",
      "temperature": 22
    },
    {
      "_created": 1465959311501,
      "_id": "93ad43d0-32a4-11e6-83ca-22000aaf0c30",
      "_modified": 1465959311501,
      "_owner": "702b5ba64301b42bc82318ae5a0459b3",
      "_version": "1",
      "power": true,
      "status": "NORMAL",
      "temperature": 28
    }
  ]
}