Object

Location /api/apps/{appID}/buckets/{bucketID}/objects/{objectID}
This resource represents an object in the bucket.

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)

Authorization
header
Required: Yes

DELETE

/api/apps/{appID}/buckets/{bucketID}/objects/{objectID}

Description

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.

Security

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

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
If-Match No string The version of the object.
If-None-Match No string Can have only "*" as value.
URL Params
Name Required? type Description
objectID Yes string The ID of the object.
Responses
204

Content-Type (None)

The object has been deleted successfully.
Note This response has no contents.
404

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

The object was not found.
Contents
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.
409

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

The object version was stale (the version specified in the If-Match header was different from the current object version on the server).
Contents
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.
401

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

Not authorized to delete the object.
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).
400

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

The bucketID was invalid (bad pattern, bad length, etc).
Contents
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}/buckets/{bucketID}/objects/{objectID}

Description

Retrieve the object.

Security

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.

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
objectID Yes string The ID of the object.
Responses
200

Content-Type application/json

The object has been retrieved successfully.
The JSON object itself. Content-Type could be specific type given on object creation.
Headers
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.
404

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

The object was not found.
Contents
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.
401

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

Not authorized to get the object.
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).
400

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

The bucketID was invalid (bad pattern, bad length, etc).
Contents
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}/buckets/{bucketID}/objects/{objectID}

Description

Verify if the object exists.

Security

The administrator can execute this action. For other users, the permission to execute this action is determined by the ACL set on the object.

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
objectID Yes string The ID of the object.
Responses
204

Content-Type (None)

Note This response has no contents.
Headers
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.
404

Content-Type (None)

The object was not found.
401

Content-Type (None)

Not authorized to check the object.
400

Content-Type (None)

The bucketID was invalid (bad pattern, bad length, etc).

PUT

/api/apps/{appID}/buckets/{bucketID}/objects/{objectID}

Description

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.

Security

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
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
If-Match No string The version of the object.
If-None-Match No string Can have only "*" as value.
URL Params
Name Required? type Description
objectID Yes string The ID of the object.
Responses
200

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

The object has been updated successfully.
Headers
Name Type Description
ETag string The version of the object.
Contents
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).
201

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

The object has been created successfully.
Headers
Name Type Description
Location string The URI to the object.
ETag string The version of the object.
Contents
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).
404

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

The object was not found.
Contents
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.
409

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

The object version was stale (the version specified in the If-Match header was different from the current object version on the server).
Contents
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.
401

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

Not authorized to put the object.
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).
400

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

The bucketID was invalid (bad pattern, bad length, etc).
Contents
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}/buckets/{bucketID}/objects/{objectID}

Description

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.

Security

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
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
If-Match No string The version of the object.
If-None-Match No string Can have only "*" as value.
URL Params
Name Required? type Description
objectID Yes string The ID of the object.
Responses
200

Content-Type application/json

The object has been updated successfully.
The updated JSON object. Content-Type could be specific type given on object creation.
Headers
Name Type Description
BodyType string The type of the object body (if available).
ETag string The version of the object.
404

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

The object was not found.
Contents
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.
409

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

The object version was stale (the version specified in the If-Match header was different from the current object version on the server).
Contents
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.
401

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

Not authorized to patch the object.
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).
400

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

The bucketID was invalid (bad pattern, bad length, etc).
Contents
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.