Introduction

When building the app for your MODE project, you may find a need for some kind of key-value storage. In particular, you may need persistent storage of data that can be shared by all members of a home. For example, you may want to store metadata such as geolocation for the home, or aggregate and store data collected from devices in the home.

Instead of implementing and operating such a data store yourself, you can simply store the data to MODE. The MODE API allows you to store information of a home as key-value pairs. It is a native functionality of MODE and requires no activation or update to your project’s settings.

The Key-Value Store API

In the REST API, the key-value store of a home is represented by the following resource:

/homes/{homeId}/kv

This API resource is restricted to callers with the proper API keys. These include:

1 Authentication token of a user session that belongs to one of the members of the home.

2 One of the project's Project API Keys.

Note that by default Project API Keys are given read-only access to the key-value store. If you want to use a Project API Key to create or update key-value pairs, you should go to your project's Settings in the Developer Console and modify the key's permissions.

For more information on project API keys, see this article.

Writing to Key-Value Store

A specific key-value pair is addressed by an API endpoint in the following format:

/homes/{homeId}/kv/{key}

where key must be unique within the home specified by homeId.

A valid key can contain alphanumerical characters, underscores (_) and dashes (-), as long as it starts and ends with an alphabet or number. Some examples:

To store a key-value pair to a home, make a PUT request to its expected endpoint. For example:

$ curl -i -X PUT -H "Authorization: ModeCloud _YOUR_API_KEY_" -H "Content-Type: application/json" -d "{\"value\": 123}" https://api.tinkermode.com/homes/HOME_ID/kv/foo

This will assign the value 123 to the key foo for home HOME_ID. In this example, the value is a number. But it could be a string, a boolean, an array, or an object. The only data type that is not allowed is null.

Note that the API call to create and update a key-value pair is the same. If the key does not already exist in the home, it will be created; otherwise, the value of the key will be overwritten with the new value.

Reading from Key-Value Store

To read a key-value pair, simply make a GET request to its endpoint. For example:

$ curl -i -H "Authorization: ModeCloud _YOUR_API_KEY_" https://api.tinkermode.com/homes/HOME_ID/kv/foo

The corresponding key-value pair JSON object will be returned:

{
  "key": "foo",
  "value": 123,
  "modificationTime": "2016-12-29T23:30:45.022Z"
}

To fetch all key-value pairs in a home, make a GET request to the key-value store endpoint like this:

$ curl -i -H "Authorization: ModeCloud _YOUR_API_KEY_" https://api.tinkermode.com/homes/HOME_ID/kv

An array of key-value pair objects will be returned.

Deleting Key-Value Pairs

To delete a key-value pair, make a DELETE request to its endpoint. For example:

$ curl -i -H "Authorization: ModeCloud _YOUR_API_KEY_" -X DELETE https://api.tinkermode.com/homes/HOME_ID/kv/foo

System-Generated Events

When a user (or a program using a Project API Key) makes changes to the key-value pairs of a home, it may be useful for other interested entities to know about the changes. For example, other members of the home may want their apps automatically update their internal states whenever that happens.

You can rely on the following special, system-generated events that are automatically triggered by the key-value store:

As far as apps and Smart Modules are concerned, these system-generated events are no different from events triggered by devices or client programs. But as a general rule, you should expect events with type names that start and end with an underscore (_) to be generated by the MODE system.