Key Value datastore Overview

IOx application can utilize datastore capability to store and retrieve key/value pair from application hosting framework. This can be very useful for an application to share smaller dataset or key/value pair to other applications.

Usage

IOx application which requests for datastore capability should include attribute "datastore" under "resources" section in package.yaml as below. During runtime, the application can invoke a REST API to store or retrieve a key/value pair. Maximum limit of 64 key/value pairs and string of length 1024 chars can be stored by IOx framework. You can find more details about the REST API in next section.

descriptor-schema-version: "2.5"
info:
  name: app2
  description: "app2"
  version: "1.0"
  author-link: "http://www.cisco.com"
  author-name: "Cisco Systems"
app:
  type: docker
  cpuarch: "x86_64"

  resources:
    profile: c1.small
    datastore: true
    network:
      -
        interface-name: eth0
        ports:
            tcp: [9000]
            
# Specify runtime and startup
  startup:
    rootfs: rootfs.tar
    target: ["python", "/usr/bin/app2.py"]

REST API

Store Key/Value pair

In order to store a key/value pair, the application needs to invoke the api (/datastore) to put the key value pair. Application can optionally specify secret password associated with the key/value pair, so that only using the secret password the key/value pair can be retrieved. Listed below environment variables are available to the application.

• DATASTORE_SERVER_IPV4
• DATASTORE_SERVER_IPV6
• DATASTORE_SERVER_PORT
• CAF_APP_ID
• IOX_TOKEN

Here is the API to which application should put the key/value pair.

Method: PUT
Absolute URI: https://{DATASTORE_SERVER_IPV4}:{DATASTORE_SERVER_PORT}/iox/api/v2/hosting/datastore
Header: "X-Token-Id": {IOX_TOKEN}, "X-Key": <key string>, "X-Value": <value string>, "X-Secret": <secret password string>

Retrieve Key/Value pair

In order to retrieve a key/value pair, the application needs to invoke the api (/datastore) to get the key value pair. If the secret password is required for getting a key/value pair then the secret string must be provided as well.

Here is the API which application should invoke to get the key/value pair.

Method: GET
Absolute URI: https://{DATASTORE_SERVER_IPV4}:{DATASTORE_SERVER_PORT}/iox/api/v2/hosting/datastore
Header: "X-Key": <key string>, "X-Secret": <secret password string>
Response:
Body:
Content-Type: applicaiton/json
Payload schema:
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "definitions": {},
    "properties": {
        "key": {
            "type": "string"
        },
        "value": {
            "type": "string"
        }
    },
    "type": "object"
}

Example application usage in python - PUT and GET

iox_ip = os.getenv("DATASTORE_SERVER_IPV4")
iox_port = os.getenv("DATASTORE_SERVER_PORT")
iox_token = os.getenv("IOX_TOKEN")
iox_app_id = os.getenv("CAF_APP_ID")

conn = httplib.HTTPSConnection(iox_ip, iox_port, timeout=10)
headers = {"X-Token-Id": iox_token, "X-Key": "abc", "X-Value": "xyz", "X-Secret": "ABC"}
url = "/iox/api/v2/hosting/datastore"
conn.request("PUT", url, None, headers)
response = conn.getresponse()

conn = httplib.HTTPSConnection(iox_ip, iox_port, timeout=10)
headers = {"X-Key": "abc", "X-Secret": "ABC"}
url = "/iox/api/v2/hosting/datastore"
conn.request("GET", url, None, headers)
response = conn.getresponse()