Creating a KiiObject

This topic explains how to create a KiiObject. For procedures for setting a JSON document in a KiiObject, see Setting a JSON Document.

Creating a KiiObject

In the following example, a KiiObject is created in a bucket "mydata" in the scope of the currently logged-in scope:

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.{APP_ID}.mydata+json" \
  "https://api.kii.com/api/apps/{APP_ID}/users/me/buckets/{BUCKET_ID}/objects" \
  -d '{"score": 1800, "name": "game1"}'

For the media type of the KiiObject, you can use either "application/json" or "application/vnd.{APP_ID}.{DATA_TYPE}" if you'd like to set a custom data type.

Kii Cloud will respond with the corresponding KiiObject ID, along with the creation time in UNIX time (msec) in UTC as shown below:

< HTTP/1.1 201 Created
< Server: Apache-Coyote/1.1
< Location: https://api.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/objects/{OBJECT_ID}
< ETag: "1"
< Content-Type: application/vnd.kii.ObjectCreationResponse+json
< Transfer-Encoding: chunked
< Date: Mon, 14 May 2012 23:45:14 GMT
<
{
  "objectID" : {OBJECT_ID},
  "createdAt" : 1337039114613,
  "dataType" : "application/vnd.{APP_ID}.mydata+json"
}

Creating a KiiObject with an ID

Kii Cloud automatically assigns an ID to a newly created KiiObject. You can also choose to have your mobile app to assign an ID to a KiiObject.

The following example creates a KiiObject with a specific ID.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.{APP_ID}.mydata+json" \
  "https://api.kii.com/api/apps/{APP_ID}/users/me/buckets/{BUCKET_ID}/objects/{OBJECT_ID}" \
  -d '{"score": 1800, "name": "game1"}'

When the KiiObject creation succeeds, the created and modified time will be returned as follows. These timestamps will be in UNIX time (msec) in UTC.

< HTTP/1.1 201 Created
< Server: Apache-Coyote/1.1
< Location: https://api.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/objects/{OBJECT_ID}
< ETag: "1"
< Content-Type: application/vnd.kii.ObjectUpdateResponse+json;charset=UTF-8
< Date: Mon, 08 Dec 2014 02:16:50 GMT
<
{
  "createdAt" : 1418005010468,
  "modifiedAt" : 1418005010468
}

Tips for accessing KiiObjects

  • Cannot write in a bucket in the application scope

    All users, including anonymous users who have not logged in yet, can read the application scope. Writing in the application scope, however, requires the users to log in. If you want to avoid forcing your application users to log in, we recommend you to leverage the "pseudo user" feature (and not to change the ACL of the application scope). See Pseudo Users for more discussion.

    You need to be careful about the security when you are using the application scope. See Security for more details.

  • Cannot read a KiiObject that has been written in a bucket

    Double check if the scope of the bucket is correct.

    Remember that buckets in different scopes are separate even if they have the same name. The same applies when you use the data browser in the developer portal.

    For example, KiiObjects created a bucket "myBucket" in the application scope are not readable from a bucket "myBucket" in a user scope.