Thing Collection

Location /api/apps/{appID}/things
All the things of the current application.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

POST

/api/apps/{appID}/things

description

Register a new thing in the current application.

Content-Type application/vnd.kii.ThingRegistrationRequest+json

The various attributes of the thing. In addition to the predefined fields listed in the Params section, you can add arbitrary custom fields. Custom fields can have any JSON value, including nested JSONs and arrays. Please note that the custom field has the following restrictions:

  • The whole size of all custom fields (field names + values) should not exceed 63 KB.
  • Custom fields are not indexed, thus you will not be able to query things with these fields.
  • The custom field name cannot start with "_". The field starting with "_" will be ignored and not stored.

Headers
Name Required? type Description
Authorization Yes string Authorization can be of type Basic or Bearer.
  • Authorization Basic: header for granting an anonymous access.
    • Set a Base64-encoded string of AppID and AppKey concatenated with a colon (APP_ID:APP_KEY).
    • The header should look like:
      Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
  • Authorization Bearer: using Oauth2 Bearer Token.
    • The header should look like:
      Authorization: Bearer ht5fpHQAyrPPwLftK1rAqllv5WNVPCnYfPiCvPocFuQ
Params
Name Required? Type Description
_vendorThingID Yes string The provided identifier (vendorThingID) of the thing. It has to be unique per application. The length must be between 1 and 200 characters with the pattern [a-zA-Z0-9-_\.].
_thingType string The type of the thing. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_vendor string The vendor of the thing. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_firmwareVersion string The firmware version of the thing. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_productName string The product name. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_lot string The prooduction lot. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_password Yes string The password for authenticating the thing. The length must be between 1 and 200 characters with the pattern \p{Print} (only printable characters).
_stringField1 string The field for storing arbitrary string data. It is indexed, so you will be able to query things based on this field. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_stringField2 string The field for storing arbitrary string data. It is indexed, so you will be able to query things with this field. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_stringField3 string The field for storing arbitrary string data. It is indexed, so you will be able to query things with this field. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_stringField4 string The field for storing arbitrary string data. It is indexed, so you will be able to query things with this field. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_stringField5 string The field for storing arbitrary string data. It is indexed, so you will be able to query things with this field. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_numberField1 long The field for storing arbitrary numeric data. It is indexed, so you will be able to query things with this field.
_numberField2 long The field for storing arbitrary numeric data. It is indexed, so you will be able to query things with this field.
_numberField3 long The field for storing arbitrary numeric data. It is indexed, so you will be able to query things with this field.
_numberField4 long The field for storing arbitrary numeric data. It is indexed, so you will be able to query things with this field.
_numberField5 long The field for storing arbitrary numeric data. It is indexed, so you will be able to query things with this field.
Sample Request 
{
  "_vendorThingID": "[string]",
  "_thingType": "[string]",
  "_vendor": "[string]",
  "_firmwareVersion": "[string]",
  "_productName": "[string]",
  "_lot": "[string]",
  "_password": "[string]",
  "_stringField1": "[string]",
  "_stringField2": "[string]",
  "_stringField3": "[string]",
  "_stringField4": "[string]",
  "_stringField5": "[string]",
  "_numberField1": "[long]",
  "_numberField2": "[long]",
  "_numberField3": "[long]",
  "_numberField4": "[long]",
  "_numberField5": "[long]"
}
Responses
201

Content-Type application/vnd.kii.ThingRegistrationResponse+json

The thing has been registered successfully.
Headers
Name Type Description
Location string URI to the new registered thing
Contents
Name Type Description
_thingID string The identifier of the thing generated by Kii Cloud.
_vendorThingID string The provided identifier of the thing.
_thingType string The type of the thing.
_vendor string The vendor of the thing.
_firmwareVersion string The firmware version of the thing.
_productName string The product name.
_lot string The production lot.
_created long The creation date of the thing in UNIX epoch format (msec in UTC).
_stringField1 string The field for storing arbitrary string data.
_stringField2 string The field for storing arbitrary string data.
_stringField3 string The field for storing arbitrary string data.
_stringField4 string The field for storing arbitrary string data.
_stringField5 string The field for storing arbitrary string data.
_numberField1 long The field for storing arbitrary numeric data.
_numberField2 long The field for storing arbitrary numeric data.
_numberField3 long The field for storing arbitrary numeric data.
_numberField4 long The field for storing arbitrary numeric data.
_numberField5 long The field for storing arbitrary numeric data.
409

Content-Type application/vnd.kii.ThingAlreadyExistsException+json

Already exists a thing with the same "vendorThingID".
Contents
Name Type Description
errorCode string Error code "THING_ALREADY_EXISTS".
message string The error message.
field string The field used for checking the duplication. It can be "thingID" or "vendorThingID".
value string The value of the field.
400

Content-Type application/vnd.kii.ValidationException+json

Happens when:
  • A mandatory field is not provided in the request
  • The value of a thing field is invalid
  • The custom fields exceed the maximum allowed size
Contents
Name Type Description
errorCode string Error code "INVALID_INPUT_DATA".
message string The error message.

POST

/api/apps/{appID}/things

Description

Register a new thing in the current application and obtain an access token for the thing.

Security

Only the administrator can obtain a persistent access token. A non-persistent access token can be obtained by anyone without any authorization.

Content-Type application/vnd.kii.ThingRegistrationAndAuthorizationRequest+json

The various attributes of the thing. In addition to the predefined fields listed in the Params section, you can add arbitrary custom fields. Custom fields can have any JSON value, including nested JSONs and arrays. Please note that the custom field has the following restrictions:

  • The whole size of all custom fields (field names + values) should not exceed 63 KB.
  • Custom fields are not indexed, thus you will not be able to query things with these fields.
  • The custom field name cannot start with "_". The field starting with "_" will be ignored and not stored.

Headers
Name Required? type Description
Authorization Yes string Authorization can be of type Basic or Bearer.
  • Authorization Basic: header for granting an anonymous access.
    • Set a Base64-encoded string of AppID and AppKey concatenated with a colon (APP_ID:APP_KEY).
    • The header should look like:
      Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
  • Authorization Bearer: using Oauth2 Bearer Token.
    • The header should look like:
      Authorization: Bearer ht5fpHQAyrPPwLftK1rAqllv5WNVPCnYfPiCvPocFuQ
Params
Name Required? Type Description
_vendorThingID Yes string The provided identifier (vendorThingID) of the thing. It has to be unique per application. The length must be between 1 and 200 characters with the pattern [a-zA-Z0-9-_\.].
_thingType string The type of the thing. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_vendor string The vendor of the thing. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_firmwareVersion string The firmware version of the thing. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_productName string The product name. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_lot string The prooduction lot. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_password Yes string The password for authenticating the thing. The length must be between 1 and 200 characters with the pattern \p{Print} (only printable characters).
_stringField1 string The field for storing arbitrary string data. It is indexed, so you will be able to query things based on this field. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_stringField2 string The field for storing arbitrary string data. It is indexed, so you will be able to query things with this field. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_stringField3 string The field for storing arbitrary string data. It is indexed, so you will be able to query things with this field. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_stringField4 string The field for storing arbitrary string data. It is indexed, so you will be able to query things with this field. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_stringField5 string The field for storing arbitrary string data. It is indexed, so you will be able to query things with this field. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_numberField1 long The field for storing arbitrary numeric data. It is indexed, so you will be able to query things with this field.
_numberField2 long The field for storing arbitrary numeric data. It is indexed, so you will be able to query things with this field.
_numberField3 long The field for storing arbitrary numeric data. It is indexed, so you will be able to query things with this field.
_numberField4 long The field for storing arbitrary numeric data. It is indexed, so you will be able to query things with this field.
_numberField5 long The field for storing arbitrary numeric data. It is indexed, so you will be able to query things with this field.
_persistentToken boolean Indicate whether the obtained token should be persistent and never expire or not. If not provided it will be "false" by default.
Sample Request 
{
  "_vendorThingID": "[string]",
  "_thingType": "[string]",
  "_vendor": "[string]",
  "_firmwareVersion": "[string]",
  "_productName": "[string]",
  "_lot": "[string]",
  "_password": "[string]",
  "_stringField1": "[string]",
  "_stringField2": "[string]",
  "_stringField3": "[string]",
  "_stringField4": "[string]",
  "_stringField5": "[string]",
  "_numberField1": "[long]",
  "_numberField2": "[long]",
  "_numberField3": "[long]",
  "_numberField4": "[long]",
  "_numberField5": "[long]",
  "_persistentToken": "[boolean]"
}
Responses
201

Content-Type application/vnd.kii.ThingRegistrationAndAuthorizationResponse+json

The thing has been registered successfully.
Headers
Name Type Description
Location string The URI of the registered thing.
Contents
Name Type Description
_thingID string The identifier of the thing generated by Kii Cloud.
_vendorThingID string The provided identifier of the thing.
_thingType string The type of the thing.
_vendor string The vendor of the thing.
_firmwareVersion string The firmware version of the thing.
_productName string The product name.
_lot string The production lot.
_created long The creation date of the thing in UNIX epoch format (msec in UTC).
_stringField1 string The field for storing arbitrary string data.
_stringField2 string The field for storing arbitrary string data.
_stringField3 string The field for storing arbitrary string data.
_stringField4 string The field for storing arbitrary string data.
_stringField5 string The field for storing arbitrary string data.
_numberField1 long The field for storing arbitrary numeric data.
_numberField2 long The field for storing arbitrary numeric data.
_numberField3 long The field for storing arbitrary numeric data.
_numberField4 long The field for storing arbitrary numeric data.
_numberField5 long The field for storing arbitrary numeric data.
_accessToken string The access token of the thing
_refreshToken string The refresh token for the obtained access token. The refresh token will not be provided when the token has been obtained with "_persistentToken=true".
409

Content-Type application/vnd.kii.ThingAlreadyExistsException+json

A thing with the same "vendorThingID" already exists.
Contents
Name Type Description
errorCode string Error code "THING_ALREADY_EXISTS".
message string The error message.
field string The field used for checking the duplication. It can be "thingID" or "vendorThingID".
value string The value of the field.
400

Content-Type application/vnd.kii.ValidationException+json

Happens when:
  • A mandatory field is not provided in the request
  • The value of a thing field is invalid
  • The custom fields exceed the maximum allowed size
Contents
Name Type Description
errorCode string Error code "INVALID_INPUT_DATA".
message string The error message.