Thing by Vendor ID

Location /api/apps/{appID}/things/VENDOR_THING_ID:{vendorThingID}
This resource represents a thing belonging to an application in Kii Cloud. The thing is accessed by its vendor thing ID.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

GET

/api/apps/{appID}/things/VENDOR_THING_ID:{vendorThingID}

Description

Retrieve the thing information.

Security

The administrator, a thing owner, and thing itself can perform this operation.

Content-Type application/json

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
vendorThingID Yes string The vendorThingID.
Responses
200

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

The thing information has been retrieved successfully. The body of the response contains both the predefined and custom fields.
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.
404

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

The thing was not found.
Contents
Name Type Description
errorCode string Error code "THING_NOT_FOUND".
message string The error message.
field string The field used for searching the thing. This can be the "thingID" or "vendorThingID" field.
value string The field value used for searching the thing.
appID string The ID of the application.
401

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

Not allowed to obtain the thing data
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

PATCH

/api/apps/{appID}/things/VENDOR_THING_ID:{vendorThingID}

description

Modify the thing information.

For the predefined fields. the fields can be added or updated, but not deleted. If a field is not provided in the request, the field will be left untouched.

For the custom fields, the fields are updated as a whole. In other words, all fields in the request will be stored as is. The fields not provided in the request will be therefore deleted.

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

The data for updating the thing.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
vendorThingID Yes string The vendorThingID.
Params
Name Required? Type Description
_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 production lot. The length must be up to 100 characters with the pattern [a-zA-Z0-9-_\.].
_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 based on 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 based on 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 based on 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 based on 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.
Responses
200

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

The thing has been updated successfully.
Contents
Name Type Description
modifiedAt long The modification date of the thing in Unix epoch (milliseconds in UTC).
404

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

The thing was not found.
Contents
Name Type Description
errorCode string Error code "THING_NOT_FOUND".
message string The error message.
field string The field used for searching the thing. This can be the "thingID" or "vendorThingID" field.
value string The field value used for searching the thing.
appID string The ID of the application.
400

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

Happens when:
  • 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.
401

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

Not allowed to modify the thing data
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

HEAD

/api/apps/{appID}/things/VENDOR_THING_ID:{vendorThingID}

description

Check if the thing is already registered.

Security

No security is involved. Anyone can perform this operation.

Content-Type application/json

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
URL Params
Name Required? type Description
vendorThingID Yes string The vendorThingID.
Responses
204

Content-Type (None)

The thing is registered.
Note This response has no contents.
404

Content-Type (None)

The thing is not registered.

DELETE

/api/apps/{appID}/things/VENDOR_THING_ID:{vendorThingID}

Description

Unregister the thing. It will also remove all thing data (buckets and objects) and ownerships. All the access tokens related with the thing will be invalidated also.

Security

The administrator, a thing owner, and the thing itself can perform this operation.

Content-Type application/json

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
vendorThingID Yes string The vendorThingID.
Responses
204

Content-Type (None)

The thing has been unregistered successfully
Note This response has no contents.
404

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

The thing was not found.
Contents
Name Type Description
errorCode string Error code "THING_NOT_FOUND".
message string The error message.
field string The field used for searching the thing. This can be the "thingID" or "vendorThingID" field.
value string The field value used for searching the thing.
appID string The ID of the application.
401

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

Not allowed to unregister the thing.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).