Object ID and URI

Kii Cloud processes various objects, such as users, groups and KiiObjects.

A unique ID and URI are given to each of these objects so that the Kii Cloud SDK can uniquely identify them as KiiUsers, KiiGroups, and KiiObjects.

Here are some examples of the ID and URI:

• For KiiUser, KiiGroup, and KiiObject, their IDs are uniquely assigned by Kii Cloud.

  • An ID of a KiiObject is unique within the bucket it belongs. The ID will be assigned automatically by Kii Cloud. You can optionally assign the ID from an application.
  • To uniquely identify a KiiObject throughout an application, you also need to have a bucket name (bucket ID) and the bucket scope (i.e., application, group, user, or thing). It is therefore recommended to use the object URI rather than the object ID when you want to distinguish the object uniquely. Note that some client SDKs do not provide the API for getting an object ID. Some SDKs mentions the object ID as "UUID".

• The KiiBucket uses the name assigned from an application as its ID. You do not need to use its URI directly if you are using the SDK.

• The URI includes the ID and uniquely identify the corresponding entity in the application.

• The REST API uses the different notation in URIs within requests.

The ID representation of Things is a bit different. See Kii Cloud SDK for Thing Overview for more details.

The following table summarizes the supported features:

*1 The bucket ID in the REST API is the bucket name in the client SDKs.

Converting an instance and its ID/URI

KiiUser, KiiGroup, KiiBucket, and KiiObject are represented as class instances in the client SDK. You can convert the instances with their ID/URIs, and vice versa.

For example, your application can save the ID or URI of a KiiObject and later use it to restore the same KiiObject instance. Note that you need to refresh the instance (i.e. load the content from Kii Cloud) after you instantiate it from the ID/URI. Otherwise, the content will be empty.

KiiUser and KiiGroup support both of ID and URI and internally convert ID and URI either way. Therefore, you can get URI from an entity generated by ID without refreshing the entity, for example.

URI and refresh

Some client SDKs' methods use an empty entity (i.e. KiiUser, KiiGroup, and KiiObject), with only URI or ID being set, as their parameters and return values.

You cannot fetch values from an entity with only URI or ID but identify an object on the cloud. Therefore, URI and ID are sufficient as a parameter of APIs which involve network access.

To the contrary, an entity with only ID or URI being set can be returned from APIs. You will need to download the values of the entity by, for example, executing the refresh method of the client SDKs to access data in the entity (The method name differs somewhat among the platforms).

Let us explain this with an example. Suppose that you know an ID or URI of a group, and you want to get a list of the group members' names. You will need to implement like the followings:

1. Create a KiiGroup instance with the ID or URI.

   The KiiGroup instance created will have only the ID/URI.

2. Execute a method for fetching the members of the KiiGroup.

   The ID/URI is sufficient for identifying the target group on the Kii Cloud, so executing the method is simple.

   As a result, you will get a list of KiiUsers. These KiiUsers are empty instances with only the ID/URIs.

3. Fetch the content of the KiiUsers to get a list of usernames.

   Here, you first need to execute the refresh method for each KiiUser. After you execute the refresh method, you can extract the usernames from the instances.