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.

Creating a bucket

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

Application scope

Unlike buckets in the other scopes, you do not need to specify an instance that a new bucket will belong to because a bucket in the application scope belongs to the application.

Execute the static method bucket(withName:) of the Kii class to create a bucket.

Swift:
```
// Create a bucket in the application scope.
let bucket1 = Kii.bucket(withName: "my_app")
```
Objective-C:
```
// Create a bucket in the application scope.
KiiBucket *bucket1 = [Kii bucketWithName:@"my_app"];
```
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).
Group scope

A bucket in a group scope stores data for the specific group.

Get a KiiGroup instance of the group that you want to create a bucket for and execute the bucket(withName:) method of the instance to create a bucket.

Swift:
```
// Create a bucket in the group scope. Login is required.
let bucket2 = group.bucket(withName: "my_group")
```
Objective-C:
```
// Create a bucket in the group scope. Login is required.
KiiBucket *bucket2 = [group bucketWithName:@"my_group"];
```

User scope

A bucket in a user scope stores data for the specific user.

Get a KiiUser instance of the user that you want to create a bucket for and execute the bucket(withName:) method of the instance to create a bucket.

Swift:

// Create a bucket in the user scope. Login is required.
let bucket3 = KiiUser.current()!.bucket(withName: "my_private")

Objective-C:

// Create a bucket in the user scope. Login is required.
KiiBucket *bucket3 = [[KiiUser currentUser] bucketWithName:@"my_private"];

Time when a bucket is created

Note that a bucket is created on Kii Cloud only when a KiiObject that belongs to the bucket is saved to Kii Cloud. For example, bucket1 will be created when a KiiObject is created and saved to Kii Cloud with the save(_:) method as follows:

Swift:

let obj1 = bucket1.createObject()
do{
  try obj1.saveSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}

let obj1 = bucket1.createObject()
obj1.save { (retObj : KiiObject?, error : Error?) -> Void in
  if (error != nil) {
    // Handle the error.
    return
  }
}

Objective-C:

NSError *error;
KiiObject *obj1 = [bucket1 createObject];
[obj1 saveSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

KiiObject *obj1 = [bucket1 createObject];
[obj1 saveWithBlock:^(KiiObject *object, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }
}];

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.