The maximum size allowed for an object is 65534 characters.
An object field with a key name bigger than 250 bytes or an string value bigger than 190 bytes will not be indexed, so you will not be able to query objects with the field.
When you are going to create a bucket together with an object, please make sure to set the bucketID with the pattern "a-zA-Z0-9_-" with the length between 2 and 64 characters.
The objectID follows the pattern "a-zA-Z0-9_-\." with the length between 2 and 100 characters.
Request Headers (Applies to all methods)
DELETE
/api/apps/{appID}/users/{userID}/buckets/{bucketID}/objects/{objectID}
Delete the object.
By setting the "If-Match: {VERSION}" header, you can execute the conditional object deletion.
- If the "If-Match: {VERSION}" header is provided, the object will be deleted only if it is not updated on the server (i.e., if the object version is not stale). Otherwise, the object deletion will fail with a 409 response.
If no "If-Match: {VERSION}" header is set in the request, the object will be deleted unconditionally. This the same when you set the "If-None-Match: *" header.
You cannot set the "If-Match: {VERSION}" and "If-None-Match: *" headers at the same time.
The administrator can execute this action. For other users, the permission to execute this action is determined by the ACL set on the object.
Content-Type application/json
- 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
Content-Type (None)
Content-Type application/vnd.kii.UserNotFoundException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "USER_NOT_FOUND". |
message | string | The error message. |
field | string | The field used for searching the user. This can be the userID or address field. |
value | string | The field value used for searching the user. |
appID | string | The ID of the application. |
Content-Type application/vnd.kii.ObjectNotFoundException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "OBJECT_NOT_FOUND". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the object. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |
objectID | string | The ID of the object that was not found. |
Content-Type application/vnd.kii.StaleVersionedObjectException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "OBJECT_VERSION_IS_STALE". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the object. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |
objectID | string | The ID of the object. |
Content-Type application/vnd.kii.UnauthorizedAccessException+json
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). |
Content-Type application/vnd.kii.InvalidBucketException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "INVALID_BUCKET". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the bucket. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |
GET
/api/apps/{appID}/users/{userID}/buckets/{bucketID}/objects/{objectID}
Retrieve the object.
The administrator can execute this action. For other users, the permission to execute this action is determined by the ACL set on the bucket and the object.
- 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
Content-Type application/json
Name | Type | Description |
---|---|---|
Last-Modified | datetime | The modification date of the object. |
X-Kii-BodyType | string | The type of the object body (if available). |
ETag | string | The version of the object. |
Content-Type application/vnd.kii.UserNotFoundException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "USER_NOT_FOUND". |
message | string | The error message. |
field | string | The field used for searching the user. This can be the userID or address field. |
value | string | The field value used for searching the user. |
appID | string | The ID of the application. |
Content-Type application/vnd.kii.ObjectNotFoundException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "OBJECT_NOT_FOUND". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the object. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |
objectID | string | The ID of the object that was not found. |
Content-Type application/vnd.kii.UnauthorizedAccessException+json
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). |
Content-Type application/vnd.kii.InvalidBucketException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "INVALID_BUCKET". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the bucket. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |
HEAD
/api/apps/{appID}/users/{userID}/buckets/{bucketID}/objects/{objectID}
Verify if the object exists.
The administrator can execute this action. For other users, the permission to execute this action is determined by the ACL set on the object.
- 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
Content-Type (None)
Name | Type | Description |
---|---|---|
Last-Modified | datetime | The modification date of the object. |
Content-Type | string | The object type (if available) or application/json. |
X-Kii-BodyType | string | The type of the object body (if available). |
ETag | string | The version of the object. |
Content-Type (None)
Content-Type (None)
Content-Type (None)
PUT
/api/apps/{appID}/users/{userID}/buckets/{bucketID}/objects/{objectID}
Replace an existing object or create a new object with the specified ID.
By setting the "If-Match: {VERSION}" or "If-None-Match: *" headers, you can execute the conditional object update/creation.
- If the "If-Match: {VERSION}" header is provided with an objectID of the existing object, the object will be replaced only if it is not updated on the server (i.e., if the object version is not stale). Otherwise, the object update will fail with a 409 response. Providing an objectID of the non-existent object with this header will also fail with a 404 response.
- If the "If-None-Match: *" header is provided with an objectID of the non-existent object, the object will be created with the specified objectID. Using this header with an objectID of the existing object will fail.
If none of these header are set in the request, the object will be either replaced unconditionally (if an objectID of the existing object is provided) or created (if an objectID of the non-existent object is provided).
You cannot set the "If-Match: {VERSION}" and "If-None-Match: *" headers at the same time.
The administrator can execute this action. For other users, the permission to execute this action is determined by the ACL set on the bucket and the object.
Content-Type application/json
The entire object with the updated data.
Headers- 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
Content-Type application/vnd.kii.ObjectUpdateResponse+json
Name | Type | Description |
---|---|---|
ETag | string | The version of the object. |
Name | Type | Description |
---|---|---|
createdAt | long | The creation date of the object in Unix epoch (milliseconds in UTC). |
modifiedAt | long | The modification date of the object in Unix epoch (milliseconds in UTC). |
Content-Type application/vnd.kii.ObjectUpdateResponse+json
Name | Type | Description |
---|---|---|
Location | string | The URI to the object. |
ETag | string | The version of the object. |
Name | Type | Description |
---|---|---|
createdAt | long | The creation date of the object in Unix epoch (milliseconds in UTC). |
modifiedAt | long | The modification date of the object in Unix epoch (milliseconds in UTC). |
Content-Type application/vnd.kii.UserNotFoundException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "USER_NOT_FOUND". |
message | string | The error message. |
field | string | The field used for searching the user. This can be the userID or address field. |
value | string | The field value used for searching the user. |
appID | string | The ID of the application. |
Content-Type application/vnd.kii.ObjectNotFoundException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "OBJECT_NOT_FOUND". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the object. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |
objectID | string | The ID of the object that was not found. |
Content-Type application/vnd.kii.StaleVersionedObjectException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "OBJECT_VERSION_IS_STALE". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the object. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |
objectID | string | The ID of the object. |
Content-Type application/vnd.kii.UnauthorizedAccessException+json
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). |
Content-Type application/vnd.kii.InvalidBucketException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "INVALID_BUCKET". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the bucket. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |
PATCH
/api/apps/{appID}/users/{userID}/buckets/{bucketID}/objects/{objectID}
Update the object partially.
If the specified fields exist in the object, their values will be updated. If the specified fields do not exist in the object, they will be added to the object. Note that you cannot delete the existing fields in the object.
By setting the "If-Match: {VERSION}" header, you can execute the conditional object update.
- If the "If-Match: {VERSION}" header is provided with an objectID of the existing object, the object will be replaced only if it is not updated on the server (i.e., if the object version is not stale). Otherwise, the object update will fail with a 409 response. Providing an objectID of the non-existent object with this header will also fail with a 404 response.
If no "If-Match: {VERSION}" header is set in the request, the object will be replaced unconditionally. This the same when you set the "If-None-Match: *" header.
You cannot set the "If-Match: {VERSION}" and "If-None-Match: *" headers at the same time.
The administrator can execute this action. For other users, the permission to execute this action is determined by the ACL set on the object.
Content-Type application/json
A JSON object with the fields to update/add.
Headers- 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
Content-Type application/json
Name | Type | Description |
---|---|---|
BodyType | string | The type of the object body (if available). |
ETag | string | The version of the object. |
Content-Type application/vnd.kii.UserNotFoundException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "USER_NOT_FOUND". |
message | string | The error message. |
field | string | The field used for searching the user. This can be the userID or address field. |
value | string | The field value used for searching the user. |
appID | string | The ID of the application. |
Content-Type application/vnd.kii.ObjectNotFoundException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "OBJECT_NOT_FOUND". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the object. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |
objectID | string | The ID of the object that was not found. |
Content-Type application/vnd.kii.StaleVersionedObjectException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "OBJECT_VERSION_IS_STALE". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the object. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |
objectID | string | The ID of the object. |
Content-Type application/vnd.kii.UnauthorizedAccessException+json
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). |
Content-Type application/vnd.kii.InvalidBucketException+json
Name | Type | Description |
---|---|---|
errorCode | string | Error code "INVALID_BUCKET". |
message | string | The error message. |
objectScope | ObjectScope | The scope of the bucket. |
appID | string | The ID of the application. |
userID | string | The ID of the user. Only provided for a user-scope bucket. |
groupID | string | The ID of the group. Only provided for a group-scope bucket. |
thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
bucketID | string | The ID of the bucket. |