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:
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 entries are allowed. Submitted values with a duplicate key will 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. To save each email we simply write it to the write API.
https://prefs.us/write/?key=...&email=janedoe@someplace.com
This would update the entry email with a new email address - no duplicates. The seconds write operation will replace the existing value.
https://prefs.us/write/?key=...&email=june.bug@whereever.com
To collect multiple emails for out waitlist, we create list called user-emails:
https://prefs.us/write/?list=user-emails&key=...&email=june.bug@whereever.com
Our list will now contain two email addresses.