Manage data

This is for:

Developer

The Stash API allows you to set, get, and remove data stored against individual keys in stash, our server-side storage system.

Prerequisites

Unique values

Before using the Stash API, you will require the following unique values:

Name Description

<tracking_id>

CEH tracking ID for the property the request is made from. This will be provided by your Customer Success manager at Coveo.

<visitor_id>

Unique site visitor ID, generated by the Smartserve script on the page and is set in the cookies qb_permanent and qbTracker.

Modules

HTTP Stash API

Usage

const createStash = require('@qubit/http-api-stash')

const stash = createStash('kv', 'spacecats_us', {
  namespace: 't001',
  useVisitorId: false,
  encrypt: false
})

stash.set('purchase').then(() => {
  console.log('Purchase data saved!')
})

  • createStash(opType, trackingId) will return a different API depending on the opType.

Options

  • namespace (string) - pass this string to prefix all of your Stash keys with ${namespace}:

    • default: none

  • useVisitorId (boolean) - pass true to prefix all of your Stash keys with ${visitorId}:

    • Will come after namespace if both are used

    • default: false

  • visitorId (string) - visitor Id to use when useVisitorId is true. If not specified, the visitorId will be retrieved from the _qubitTracker cookie

    • default: none

API

kv

  • set(key, value)

Stores the value against the key. If a value already exists against the key, it will be overwritten with the provided value. There is no shelf ­life to these key-value stores, once set they are available forever.

  • get(key)

Retrieves the value stored at the specified key.

  • get(keys)

Retrieves the values stored at all the keys specified in the keys array.

Sample response:
{
  "key1": "value1",
  "key2": "value2"
}

deferkv

  • set(key, value, timestamp, route)

Sets a value that will expire at a specific time instant in the future. timestamp is a user defined UNIX timestamp at which the set value can be expired from Stash.

Using the same timestamp again will overwrite the previous entry. You can also specify an optional (mandatory right now for this module) routing key.

For now, deferred operations can not read or write to protected storage, so the access level is set as public.

  • remove(key, timestamp)

Removes the entire row associated with the given key and timestamp and is used to delete the data that was set using the set operation.

  • get(key, timestamp)

Retrieves the stored data value and routing key against the given key and timestamp.

Sample response:
{
  "value": "val_123",
  "route": "r4"
}

ts

  • set(key)

Store the UNIX timestamp, calculated at the server, for the moment when the request is received against the specified key.

  • get(key)

Retrieves the stored UNIX timestamp at the specified key.

count

  • increment(key, dimension)

Increment by 1 the counter specified by the key and the dimension_type. Currently only 'date' works. This will return the key of the counter which this has incremented and will be in the format of key:dimension_value.

Sample response:
{
  "key_123": "2017-07-31"
}

  • decrement(key, dimension)

Decrement by 1 the counter specified by the key and the dimension_type. Currently, this is hardcoded to 'date', as this as it’s the only supported. This will return the affected counter key as above.

  • get(key)

Retrieves the value of the count stored against the provided key. Note that the key is what we return in the increment and decrement functions.

  • get(keys)

As above, but when you provide a keys array, you will receive an object containing all the counts for those keys.

Setting a value

Setting a value in the Stash API is made via a POST request.

POST //stash.qubitproducts.com/stash/v1.1/kv/set/<tracking_id>/public/<visitor_id>:<key_name>
DATA '{'data':'<value>'}'

The types of <key_name> and <value> must both be string with the key name being URL friendly.

On a successful set, the response to this request will be:

{ "status": 200 }

Retrieving a value

Getting a value in the Stash API is made via a GET request.

GET //stash.qubitproducts.com/stash/v1.1/kv/get/<tracking_id>/public/<visitor_id>:<key_name>

The <key_name> must be string .

If the key exists, the response will be as below, where <value> is the value stored on that key. If the key does not exist, then the status code will be 404.

{
  "status": 200,
  "data": "<value>"
}

Retrieving multiple values

It is possible to retrieve multiple values at once using the batch endpoint. This requires sending an array of keys to fetch.

// POST stash.qubitproducts.com/stash/v1.1/kv/getbatch/<tracking_id>/public
{
  "keys": [
    "<visitor_id>:<key_name>",
    "<visitor_id>:<key_name>",
    "<visitor_id>:<key_name>"
  ]
}
Note

The batch size limit is 10 keys.

For the keys that exist, then the response will be as below:

{
  "status": 200,
  "data": {
    "<visitor_id>:<key_name>":"<count>",
    "<visitor_id>:<key_name>":"<count>",
    "<visitor_id>:<key_name>":"<count>"
    // ...
  }
}

Response codes

Each response message contains a response code, which indicates the status of the original query. The format of the response will be JSON such as the below:

{ "status": 200 }

This response code can be checked to quickly determine whether a query was successful or a retry needs to be made. Note that this is not related to the actual HTTP response code, which will always be 200.

Code Description

200

The operation completed successfully

400

The operation did not complete due to a client side error. This code will be returned when the request parameters had invalid values

404

The operation did not complete due to a client side error. This will be returned when the requested key or keys are not found

500

The operation could not be completed due to a server side error. A retry needs to be made in this case

FAQs

Is the Stash API writable from the client?

Qubit has two endpoints, the Protected Stash API and the Public Stash API. The Protected Stash API is only readable from the client side, the Public Stash API is also writable.

Can client-side code change previously written data in the Stash API?

Yes, but only for the Public Stash API.

Can client-side code create/update data which was uploaded via the CSV upload tool?

This is only possible via the Public Stash API at the moment, which is both read/writable from the client side.