Web Storage API

From SpinetiX Support Wiki

Jump to: navigation, search

Introduction

The web storage specification, standardized by the World Wide Web Consortium (W3C), has been used to implement a permanent & semi-permanent storage of structured key-value pair data on the HMP.

The following APIs are available:

  • JavaScript API
    Provides mechanisms for storing key-value pair data on the HMP, respectively on Elementi, using JavaScript code. Added in 3.0.0 firmware.
  • REST API
    Provides RESTfull web services for reading and writing webstorage variables onto the player from external clients through HTTP(S) calls. Added in firmware 4.3.0.

JavaScript API

The JavaScript API provides two mechanisms for storing key-value pair data on the HMP, respectively on Elementi, using JavaScript code. It was added in 3.0.0 firmware to complement the Shared Variables API usage, especially in what concerns the permanent storage of data (i.e. resilience to player restarts) - it also has the advantage that the value of a item (i.e. object property) can be read at any time independently on the time it has been set.

The two mechanisms refer to these global objects:

  • localStorage for permanent data storage, including upon player restart or publish of new content.
  • sessionStorage for semi-permanent storage, as the data is reinitialized whenever the content restarts (i.e. following a restart or a publish).

localStorage

The localStorage object enables permanent storage of data, being resilient to player reboots. It provides access to a list of key/value pairs (sometimes called items), that can be set and / or read with the following methods:

// setter
localStorage.setItem(key, value);

// getter
localStorage.getItem(key);

// remove item
localStorage.removeItem(key);

// remove all items from the local storage
localStorage.clear();

The data stored into the web storage on the HMP can also be cleared from HMP Control Center by going to:

sessionStorage

The sessionStorage object is identical to the localStorage object, except that the data is reinitialized whenever the content restarts, following a player reboot or a new publish. It provides access to a list of key/value pairs (sometimes called items), that can be set and / or read with the following methods:

// setter
sessionStorage.setItem(key, value);

// getter
sessionStorage.getItem(key);

// remove item
sessionStorage.removeItem(key);

// remove all items from the session storage
sessionStorage.clear();

Usage

  • Only strings can be stored in the web storage - attempting to store a different data type will result in an automatic conversion into a string. Conversion into JSON (JavaScript Object Notation), however, allows for effective storage of JavaScript objects.
  • When invoking the methods above, except for the getter, a storage event is fired.
  • The maximum size for each of the two web storage objects is 4 MB - see above how the data can be cleared.
  • Starting with 3.1.0 firmware release, the items saved into Web Storage can also be accessed as JavaScript properties (e.g., localStorage.key). At the same time, the Shared Variables framework was changed to have Shared Variables automatically saved into the localStorage object, thus having their values kept upon HMP reboots; updating a Shared Variable triggers a modification within the localStorage object as well.

REST API

Applies to HMP350.

The REST API was added in firmware 4.3.0 to allow reading and writing variables (i.e. localStorage data) onto the player from external clients through HTTP(S) calls. REST stands for "Representational State Transfer", which is a software architectural style that defines a set of constraints to be used for creating web services.

The following operations are supported:

  • List all existing variables
  • Get a variable value
  • Set the value of one or more variables

The REST API is deactivated by default - to use it, open Advanced Applications > Webstorage API page in HMP Control Center, activate "Enable security token access to the Webstorage API" option and click the "Apply" button.

Authentication

To access the API end-points, the security token, generated and stored on the player, must be provided with each call, through a "Bearer Authorization" header or an "access_token" query string parameter. Authentication is done using the credentials of users defined in user manager, with content authoring or admin rights. Both TLS-SRP and HTTP Basic authentication methods are supported.

Note Note:
Using http is not secure, any eavesdropper can steal the bearer token or user password - using https, either with self-signed certificate or with TLS-SRP is a secure alternative.

End-points

The base URL is http(s)://HMP_address/webstorage and the following operations are possible:

  • GET http(s)://HMP_address/webstorage
    Get the list of webstorage variables on the player.
  • GET http(s)://HMP_address/webstorage/{key} or GET http(s)://HMP_address/webstorage?name={key}
    Get the value of the variable named {key}.
  • POST http(s)://HMP_address/webstorage/
    Update one of more variables using the content of a form.
  • POST http(s)://HMP_address/webstorage/{key} or POST http(s)://HMP_address/webstorage?name={key}
    Update the variable named {key} with the content of the POST.
  • POST http(s)://HMP_address/webstorage/{key}?expect={value}
    Update the variable named {key} with the content of the POST, only is the previous value of the variable is equal to {value}.
  • DEL http(s)://HMP_address/webstorage/{key}
    Delete the variable named {key}.
Note Note:
The full documentation, including examples, can be found here: https://api.docs.spinetix.com/ .

See also

This page was last modified on 20 November 2018, at 16:46.