Skip to content

Organizing data

Grouping sets of values

Often it may be necessary to organize your preferences or settings by grouping them according to context, their purpose, or a project.

The API has ability to group or categorize submitted values. It is definitely advisable to somehow group or categorize your data items (either by project, or a domain, etc.) - but the need will clearly depend on your use case. There is a way to logically organize the data into groups.

Groupings can be: 'project', 'domain', 'subdomain', and 'list'. To assign a piece of data to a group (like domain, subdomain, project name, or a list), add the parameter to your /write? query.

Those are all optional values but they may help tremendously with your data queries later. A full list of reserved grouping parameters is listed below.

Grouping query example

The /write? query below will save email addresses collected via a landing page for a project "my_ap" and knowledge domain we called "front-page". 

https://prefs.us/write/?project=my_app&domain=front-page&email=janedoe@someplace.com&list=waitinglist&key=[apikey]

The above query creates a list called "waitinglist" within the project named "my_app" and domain "front-page".

The full list would then be retrieved with a /read? query:

https://prefs.us/read/?project=my_app&domain=front-page&list=waitinglist&key=[apikey]

Reserved keywords

The following keywords are used to identify a group of values. The keywords are all very abitrary - they are plain strings, and there is no meaning behind the names, and there is no naming convention. Their purpose is only to help with organization of the data. They can be combined together, so a domain can have several projects, or a single project several domains, it really is up to you, the developer, to decide how to organize the data for your own benefit.

Key name Description
key A unique key associated with sets of data (API Key)
project grouping variable
domain grouping variable
subdomain grouping variable
type [reserved]
list grouping variable; creates a list type collection

What are Lists?

Lists basically are collections of data grouped by a list name where duplicate keys are allowed. Submitted values with a duplicate key would typically be overridden. Unless (!) they are stored in a list. Lists are created by adding &list=[listname] parameter to your /write queries.

For instance, let's say we have a landing page for a product which collects emails of users interested in being notified about product updates. Normally, to save an email we'd simply send it to the write API:

https://prefs.us/write/?key=[apikey]&email=janedoe@someplace.com

Great! The problem is that if a field "email" already exists, this would update the email value with the new address - no duplicates. The seconds write operation (as shown below) will replace the existing value.

https://prefs.us/write/?key=[apikey]&email=june.bug@whereever.com

To collect multiple emails for out waitlist, we create a list called user-emails:

https://prefs.us/write/?list=user-emails&key=[apikey]&email=june.bug@whereever.com

Our list will now contain two email addresses.

prefs_us.using("[apikey]")
    .list("user-emails)
    .write("email=june.bug@whereever.com");

import com.gorny.prefsus;

PrefsUs.using("[apikey]").write("email=june.bug.wherever.com");

import prefus

String apiKey = prefsus.using("[apikey]");

def callback(R):
    print("Received: ", R)

prefsus.list("user-emails").write("email=june.bug.wherever.com")

You can review server's response by supplying a callback to write command.

prefs_us.using("[apikey]");

prefs_us.list("user-emails").write("email=maciej.gorny@siriusxm.com", 
    (response) => {
        console.log("[write] Response %o",response);
    }
);

import com.gorny.prefsus;

PrefsUs.using("[apikey]").list("user-emails).write("cat.grrl@wherever.com", (response)->{
    System.out.println(response.toString());
} );

import prefus

String apiKey = prefsus.using("[apikey]");

def callback(R):
    print("Received: ", R)

prefsus.list("user-emails").write("email=june.bug.wherever.com")