Creating a Bucket

To store data in Kii Cloud, you first need to create a bucket.

Bucket name

You can assign any name to a bucket according to the following rules. The bucket name is used to reference the bucket later.

The naming rules for buckets are as below:

• The following names are reserved and cannot be used.
  • users
  • devices
  • installations
  • internal
  • things
• The bucket name cannot start with "_" (underscore).

• The bucket name can be a string of 2 to 64 characters. Valid characters are alphanumeric, "_" (underscore), and "-" (hyphen).

• You can use the same name for multiple buckets as far as each of the buckets with the same name is unique within the application scope, a group scope, and a user scope. These buckets are recognized individually.

In the Kii documentation, the bucket name is denoted as {BUCKET_ID}. Replace the placeholder {BUCKET_ID} with the bucket name.

Resource URL for a bucket

You can create a bucket in any of the application scope, a group scope, and a user scope.

The scope of a bucket determines the resource URL for accessing the bucket.

See Resource URL and user representation to learn how to specify the <selector> part for the user scope. See Resource URL and thing representation to learn how to specify the {THING_ID} part for the thing scope.

Here is an example of creating a new bucket with a new KiiObject for each scope.

• In the application scope

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

  As mentioned earlier, replace the placeholder {BUCKET_ID} with the bucket name.

  The application scope is accessible to all users, so the scope is useful for storing the application assets. If the data that can be represented in the JSON format (e.g., text data and application config), you can store them as key-value pairs of KiiObjects. If the data are binary (e.g., images and sounds), you can upload them as an object body.

  Be careful about security when using the application scope. As explained in Security, anyone can access the data in the application scope if they know the AppID and AppKey. Storing confidential data such as customer's personal information in the application scope is, therefore not safe. For storing such data, consider preparing a region that can be accessible only to the app administrator. You can achieve this by leveraging the server code and ACL modification (See Administrator for some implementation hints).

• In a group scope

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

• In a user scope

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

• In a thing scope

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

Hint for creating a bucket list

If you need to get a list of buckets, you need to implement the feature in your application.

Usually, buckets are created statically with their names in your code, so you should not need to get a list of buckets. If you do need to get the bucket list for some reasons (e.g., your code dynamically create buckets), your application can use a dedicated application scope bucket to store all bucket names. See Hint for creating a user list to learn how you can implement it.