Skip to content

Introduction

A Short-Lived Disposable Settings API

Sometimes we just need a quick way to persist some data without getting into creating a dedicated data store. Or maybe we just don't want to pollute an existing storage with temporary data that is ephermal in nature and we only need for a short little while. Demo apps, mock ups, static pages... are all use cases for this service.

Well, say hello to prefs.us!

  • No accounts. No logins.
  • No databases to create and maintain.
  • No backend: allow your apps to save and retrieve data directly.
  • Secured with password-based encryption processes.

The idea is to be able to quickly store and retrieve some data with minimum fuss. With that goal in mind, the API was designed to be as frictionless as possible. The service does not require a login or accounts on your part.

How does it work?

Let's say you you build a frontend and need to preserve some user-specific data, like user preferences, settings, config, etc. When saving to locatStorage is often a choice, it has two fundamental flaws:

  1. the data gets wiped when user cleans the browser data
  2. the data does not persist across devices.

This is where prefs.us shines. It can be used like local storage but it will survive device resests, data wipes, and user will be able to resume on different devices.

The API key (token) is generated on the fly, as neeeded, using the credentials/secrets provided by your users, like a name and a passphrase, anything at all that would the token unique for your users. Those credentails never leave the browser, they are never transmitted anywhere, and never stored anywhere.

Once that step is completed you can store and retrieve data for that particular user.

Why Prefs.us API is a better localStorage alternative?

Yes, local storage in the web browser is very convenient and easily accessible but suffes from a few major shortcomings:

  1. Local storage does not survive data wipe or device reset. When users clear the browser cache they will loose the data.

  2. Local storage is not secure: data stored in plain text. Susceptible to injection attacks.

  3. Rather low limit of 5 MB of storage.

  4. No device switching. Data saved with LocalStorage on one device cannot be retrieved on another.

  5. LocalStorage offers synchronous operation only. This means each read or write will be done one-at-a-time. Prefs.us API was designed from the ground up to be asynchronous.

  6. LocalStorage can't be used by web workers. If you build an application that does background processing, localstorage may be out of reach.

Prefs.us API addresses all of the above shortcomings with a simple, clean, and secure API.

Data security

The API utilizes Password-Based Encryption process to generate a unique API token which will govern the use of your or your users' data. Any credentials supplied by your users or secrets supplied by your app are contained within the scope of the client. They never leave the browser.

  • Data-in-motion. All communication and traffic between the client (your app) and the server server is secured with industry standard HTTPS protocol. Even though your app may not use http (not recommended), and and all communication with the API is over HTTPS.

  • Data-at-rest. All data is stored encrypted secured by AES-256 encryption algorythm.

As of now there are two types of data that can be managed with prefs.us:

  1. Key/value pairs and

  2. Lists.

Key-Value pairs

Key/value pairs are fairly self-explanatory, each "key" may be assigned a "value". Duplicate assignments will result in a value (for a given key) be overwritten.

prefs_us.key("user")
        .write('{"score":"200", "level":"3" }');

Lists and collections

Lists are unordered collections of values. We add and remove items to and from a list by specifying a list's name and a value we want added (or removed).

prefs_us.list("signups")
        .add("jane.doe@somewhere.com");

// uses a callback 
prefs_us.list("signups")
        .read( (data) => {
            console.log(data.values);
        });

Organized and grouped data

Each API token can organize and store your data under any number of "projects", "domains", or "subdomains". There is no inherent meaning behind those terms, they are just grouping keywords for organizing your data.

var gameJson = {...};

prefs_us.domain("ultimafaux")
        .key("user")
        .write(gameJson);

Callbacks and Promises

Retrieve data using callback functions or handle Promise directly, whatever fits your style.

// uses a callback 
prefs_us.domain("ultimafaux")
        .key("user")
        .read( (data) => {
            gameJson = data.value;
        });

// same as above but uses Promise
prefs_us.key("user").read()
    .then( (response) => response.json())
    .then( (data) => {
        console.log(data.values);
    })
    .catch( (error) => {
        console.log(error.name);
    });

Time-To-Live

You can set an arbirary time-to-live constraint on any piece of data. Inactive data will be purged from the system when TTL has been reached. Inactive means it was not read nor written to (updated) within TTL time window.

var stuff = {...};

// store game state for 90 days
prefs_us.domain("demostuff")
        .project("myclient")
        .ttl(10)
        .key("proposal123")
        .write(stuff);
The above entry will be automatically purged from the system after 10 days of inactivity (no reads or writes).