The Simple Secure Key-Value API is a JSON Action API that uses keys to store and retrieve JSON values. It is part of FairCom's "admin" api. It is optimized for high-speed and security. One FairCom server can support thousands of concurrent users storing and retrieving thousands of key-value pairs per second. To maximize throughput, each action can set or retrieve many key-value pairs.

An application can use it to store any key-value pair, such as a user profile, user preference, user-defined query, application settings, role settings, and so forth. Keys can be hierarchical and values can be any JSON value, such as an object, array, string, number, true, false, or null.

The API provides three keystores with different security scopes. The global keystore is shared by all authenticated users, which is useful for application settings. The role keystore shares keys among users with the same role, which is useful for role-specific settings. The user keystore isolates keys to each user, which is useful for a user's settings. For example, a user with an operator role can access keys assigned to the operator role, keys assigned to the user, and keys in the global keystore.

Keystore Details

• Global: The Global keystore is available to any authenticated user. Its keys are independent from the other stores. An application uses it to store general settings for all users. 
• Role: The Role keystore is available to an authenticated user with a specific role. Each role has an independent set of keys. An application typically uses it to store settings that apply to an application role, such as a manager, operator, or engineer. The currently logged-in user must have the specified role. Any user with the specified role can modify the key-value pairs for all users who have that role. An administrator account may set and get values for any role.
• User: The User keystore is available to the currently logged-in user. Each account has an independent set of keys. A user can set and get key-value pairs only for its account. This keystore is designed for an application that logs each user directly in the FairCom server, as opposed to using an application account. This allows the API to enforce the RBAC privileges assigned to that user. An administrator account may set and get values for any account.

Keystore Features

Each keystore provides the following features:

• 128-byte keys
• 2 GB JSON values
• Keys can optionally include a string of your choice to create hierarchies.
• You can set and retrieve the value assigned to a key.
• You can retrieve all keys or key-value pairs at a specified level of the key hierarchy.
• Each key-value pair provides basic auditing information about the user who created or last updated it. It also tracks the timestamp when it was created and last updated.

The API does not support the following features:

• It does not support time-to-live for key-value pairs.
• It does not support secondary indexes. Thus, it cannot query the JSON properties stored inside values. 
• It does not support sharded data for global-scale applications.

How to use hierarchical keys

The Simple Secure Key-Value API supports hierarchical keys and allows you to implement them any way you want.

A common approach is to create a key hierarchy using a delimiter string. For instance, if you use the forward slash character, "/", as a delimiter, "color/" acts as a parent to keys like "color/red" and  "color/green". The delimiter string is typically one ASCII character, but it can be multiple characters or multi-byte UTF-8 characters.

To ensure consistent hierarchical matches, you can ensure each level in the hierarchy ends with the delimiter string, and only assign key-value pairs to keys that don't end with the delimiter.

Applications often use the forward slash character / in keys to create a hierarchy:

• "myApp/"
• "myApp/queries/"

Applications typically assign and retrieve key-value pairs to leaf nodes that do not end with the delimiter string:

• "myApp/queries"
• "myApp/queries/My Favorite"
• "myApp/queries/Find Errors"

Applications can use the hierarchy to retrieve keys and key-value pairs from any level of the hierarchy. For example, the following keys are available at "myApp/queries/". 

• "myApp/queries/My Favorite"
• "myApp/queries/Find Errors"

The "keyWithoutHierarchy" property contains the remainder of the key following the "partialKey" property. For example, the following leaf keys are available at "myApp/queries/". 

• "My Favorite"
• "Find Errors"

A key without its hierarchy is useful when an application lets users save items with user-defined names. The application can use the key-value API to store these items. To organize these items, the application typically creates a key like "myApp/queries/My Favorite". It uses a fixed hierarchical value at the beginning of the key, such as "myApp/queries/" and assigns the remainder of the key to the user-defined name for the item, such as "My Favorite". The "keyWithoutHierarchy" property contains the user-defined name.

Tip: The Simple Secure Key-Value API does not limit you to this common approach. 

• You may define a hierarchy with a multi-character delimiter, such as "||".
• You may assign a key-value pair to any key string, such as "color/" and "color".
• You may use the "partialKey" property to match any partial key string, such as "myApp/queries/My Fav".