Thing Management

Kii Cloud lets you manage things by offering the following features.

Register a Thing

By registering a thing, it will be acknowledged by Kii Cloud.

Upon the thing registration, you can set various fields as the thing information (See the overview for the explanation of each field).

Here is an example of registering a thing.

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "Content-Type: application/vnd.kii.ThingRegistrationAndAuthorizationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things" \
  -d '{
        "_vendorThingID": "nbvadgjhcbn",
        "_thingType": "CAMERA",
        "_password": "123456",
        "freeFormField1": "freeFormValue1",
        "freeFormField2": "freeFormValue2",
        "freeFormField3": "freeFormValue3"
      }'

You register a thing with Basic Authentication. Replace {BASE64_ENCODED_APPID_AND_APPKEY} with a Base64-encoded string of concatenated AppID and an arbitrary value with a colon (:) in between the two values.

Upon a successful registration, a 201 response is returned like this:

201

Content-Type: application/vnd.kii.ThingRegistrationAndAuthorizationResponse+json
{
    "_thingID" : "th.dfa848a00022-faea-4e11-dacb-0614e078",
    "_accessToken" : "X7BGXok7oDDNSIEXo-sNdhMIq1qNpd1DWNrrpifjPY4",
    "_vendorThingID" : "nbvadgjhcbn",
    "_thingType" : "CAMERA",
    "_created" : 1411490350034,
    "freeFormField1" : "freeFormValue1",
    "freeFormField2" : "freeFormValue2",
    "freeFormField3" : "freeFormValue3"
}

The thingID and the (non-persistent) access token are placed in the "_thingID" and "_accessToken" field, respectively. The creation time (UNIX time in milliseconds) in UTC is also put in the "_created" field.

You can also register a thing without getting any access token by sending a request with the content type application/vnd.kii.ThingRegistrationRequest+json.

Once registered, a thing can be identified via its thingID or its vendorThingID (the latter only available on some thing-related REST API).

In this guide, we will show curl execution samples with the thingID. If you want to use the vendorThingID instead, please replace the {THING_ID} in the curl execution samples with the VENDOR_THING_ID:{VENDOR_THING_ID}.

Check if a Thing is Registered

Any authenticated users and things can check if a thing is registered in the backend like this:

curl -v -X HEAD \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}"

If the thing is registered, a 204 response is returned. If it is not registered, the response will be a 404.

Get an Access Token

Just like a user getting his access token by submitting his username and password, a thing can get its access token by submitting its vendorThingID and password as follows:

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "Content-Type: application/vnd.kii.OauthTokenRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/oauth2/token" \
  -d '{
        "grant_type": "password",
        "username": "VENDOR_THING_ID:KQgn3WEIXDffAoU5ZZgA",
        "password": "p455w0rd"
      }'

You get an access token with Basic Authentication. Replace {BASE64_ENCODED_APPID_AND_APPKEY} with a Base64-encoded string of concatenated AppID and an arbitrary value with a colon (:) in between the two values.

The granted token is non-persistent. The non-persistent token will expire if the thing is disabled or when its expiration date comes. When the thing is re-enabled, for example, it needs to get a new access token.

Sometimes, the capability of a thing is so limited that it cannot securely store a password. In this case, the thing has no way to request a new access token. To accommodate such a situation, Kii Cloud provides a persistent token. This token only expires when the thing is unregistered. The persistent token will not expire when the thing is disabled. It will just be invalidated temporarily until the thing is enabled again. You can, for example, embed a persistent token in a thing so that it can keep using the same token again and again.

To get a persistent token, please set the "_persistentToken" field true when registering a thing, like in the following example. Please note that only the application administrator can get the persistent token.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingRegistrationAndAuthorizationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things" \
  -d '{
        "_persistentToken": true,
        "_vendorThingID": "nbvadgjhcbn",
        "_thingType": "CAMERA",
        "_password": "123456",
        "freeFormField1": "freeFormValue1",
        "freeFormField2": "freeFormValue2",
        "freeFormField3": "freeFormValue3"
      }'

Manipulate the Thing Information

Getting the Thing Information

A thing, thing owners, and application administrator can retrieve the thing information like this:

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}"

The thing information will be returned as a 200 response as follows:

200

Content-Type: application/vnd.kii.ThingRetrievalResponse+json

{
    "_thingID": <thingID>,
    "_vendorThingID": <vendorThingID>,
    "_created": 1337039114613,
    "_thingType": "CAMERA",
    "freeFormField1": "freeFormValue1",
    "freeFormField2": "freeFormValue2",
    "freeFormField3": "freeFormValue3",
    "_online": true,
    "_onlineStatusModifiedAt": 1431611669239
}

Besides from the fields in the thing information, two additional fields (_online and _onlineStatusModifiedAt) are also returned. These fields show the current thing status.

  • _online shows the current status of the thing. The value is true if the thing is online. The value is false if the thing is offline.

  • _onlineStatusModifiedAt shows the last time when the thing status has changed (in UNIX time, msec).

Updating the Thing Information

A thing, its owners and application administrator can update the thing information like this:

curl -v -X PATCH \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingUpdateRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}" \
  -d '{
        "_thingType": "New Thing Type",
        "freeFormField1": "freeFormValue1",
        "freeFormField2": "freeFormValue2"
      }'

For the predefined fields, only the specified fields will be updated. The fields not specified in the request will remain unchanged. You cannot delete the existing fields.

For the custom fields, they are updated as a whole. This means that all fields specified in the request will be saved while the fields that have not been specified will be deleted.

If the update is successful, a 200 response will be returned with the modified time (in UNIX, milliseconds) in UTC:

200

Content-Type: application/vnd.kii.ThingUpdateResponse+json

{
  "modifiedAt" : 1411553060944
}

Converting between thingID and vendorThingID

Get the thing information in order to get the thingID from its vendorThingID or to get the vendorThingID from its thingID.

  • Get the vendorThingID from the thingID

    Get the thing information with the URL https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID} and check the value in the _vendorThingID field.

  • Getting the thingID from the vendorThingID

    Get the thing information with the URL https://api-jp.kii.com/api/apps/{APP_ID}/things/VENDOR_THING_ID:{VENDOR_THING_ID} and check the value in the _thingID field.

Manipulate the Thing Status (Enabling and Disabling)

Thing owners and application administrator can disable the thing. If the thing is disabled, the thing is "locked" and it will not be able to access its data resources (i.e. buckets and objects in the thing scope). The data resources themselves are kept in the backend and the thing owners and the application administrator can still access them. The feature is useful, for example, when the thing is lost or stolen.

The thing owners and application administrator can, of course, re-enable the thing. Once the thing is enabled, it is "unlocked" and it will regain the access to its data resources.

Disabling/Enabling a Thing

Here is an example of disabling a thing.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingStatusUpdateRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/status" \
  -d '{"disabled": true}'

If successful, a 204 response is returned.

To enable the thing, set the "disabled" field to false.

Checking if a Thing is Disabled

A thing, its owners, and application administrator can check if the thing is disabled or not.

Here is an example of checking if a thing is disabled:

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/status"

A 200 response will be returned like this:

200

Content-Type: application/vnd.kii.ThingStatusRetrievalResponse+json

{
    "disabled": true
}

Unregister the Thing

A thing, its owners, and application administrator can unregister the thing. Once the thing is unregistered, all its data resources (i.e. buckets and objects) are deleted from the backend.

Here is an example of unregistering a thing:

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}"

When successful, a 204 response will be returned.

Get a List of Owned Things

Any authenticated users can get a list of things that the users are currently owning (See Ownership Management to learn how to manage the thing ownership).

Here is an example of getting a list of owned things.

curl -v -X POST \
  -H "Authorization: Bearer {OWNER_ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingQueryRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/query" \
  -d '{
    "thingQuery" : {
      "clause" : {
        "type" : "contains",
        "field" : "userOwners",
        "value" : "{USER_ID}"
      }
    }
  }'

The list is returned as follows:

200 OK
Content-Type: application/vnd.kii.ThingQueryResponse+json

{
  "queryDescription" : "WHERE ( userOwners = '{USER_ID}' )",
  "results" : [ {
    "_thingID" : "{THING_ID_OF_THING_01}",
    "_vendorThingID" : "{VENDOR_THING_ID_OF_THING_01}",
    "_thingType" : "{THING_TYPE_OF_THING_01}",
    "_firmwareVersion" : "{FIRMWARE_VERSION_OF_THING_01}",
    "_created" : {CREATED_DATE_OF_THING_01},
    "_disabled" : false
  }, {
    "_thingID" : "{THING_ID_OF_THING_02}",
    "_vendorThingID" : "{VENDOR_THING_ID_OF_THING_02}",
    "_thingType" : "{THING_TYPE_OF_THING_02}",
    "_firmwareVersion" : "{FIRMWARE_VERSION_OF_THING_02}",
    "_created" : {CREATED_DATE_OF_THING_02},
    "_disabled" : false
  } ]
}

If the user owns no thing, an empty list is returned.

More examples

A user can list up all things he owns as a user and as a group member.

Please set both user ID and group ID using the or clause like in the following example:

{
  "thingQuery" : {
    "clause" : {
      "type" : "or",
      "clauses": [ {
        "type" : "contains",
        "field" : "userOwners",
        "value" : "{USER_ID}"
      }, {
        "type" : "contains",
        "field" : "groupOwners",
        "value" : "{GROUP_ID}"
      } ]
    }
  }
}

A user can filter things by putting additional conditions on the thing's predefine fields.

Please use the and clause like in the following example:

{
  "thingQuery" : {
    "clause" : {
      "type" : "and",
      "clauses": [ {
        "type" : "contains",
        "field" : "userOwners",
        "value" : "{USER_ID}"
      }, {
        "type" : "eq",
        "field" : "_thingType",
        "value" : "{THING_TYPE}"
      } ]
    }
  }
}

Note that the contains field is mandatory.

Please refer Query Request Object to learn how you can set the conditions with the available clauses. You can set the thingQuery similarly as you would set the bucketQuery.

Pagination

If the number of things in the list is bigger that the one that can be put in one response, the list will be paginated; a portion of the things will be returned together with a pagination key.

Please refer Query Request Object and Pagination (object query) to learn how you can leverage the pagination feature. You can control the pagination similarly as you would do for the object query.

Hint for Getting a List of All Things

The API introduced in this section only returns things owned by the user. If you need to get a list of all things, including the ones that are not owned by the user, you need to implement the feature in your application. For example, your application can use a dedicated application scope bucket to store information of all things. See Hint for creating a user list to learn how you can implement it.

Force Change Thing Password

The application administrator can force change a thing's password. This feature is designed to handle the situation like a thing password being leaked.

curl -v -X PUT \
  -H "Authorization: Bearer {APP_ADMIN_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ChangeThingPasswordRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/password" \
  -d '{
        "newPassword": "{NEW_PASSWORD}"
      }'

Kii Cloud returns a 204 response when the password is successfully changed.

Invalidate tokens

When a thing password is changed, all non-persistent tokens that have been issued to the thing will be invalided.

Note that all persistent tokens will stay valid. The thing owner's tokens will stay valid too.