To save data:
To retrieve data:

So why prefs.us? Sometimes we just need a quick way to persist some data, like configuration or user preferences, without getting into setting up a full blown data store. Demos, mock ups, proof of concept, all are use cases for this service. For example, I myself wanted at one time to quickly store email addresses submitted via a landing page.

This simple service allows to sumbit key=value pairs as parameters in a standard HTTP GET request. You write and read them with the help of a unique token (hash, key, whatever...) which you will get with a successul response. That token can also be generated ahead of time for subsequent repeated use.

All values submitted are disposable and are automatically destroyed after some time of inactivity (i.e. not accessed for some time) Some things to be mindful of:

1. Keep and use the same key for all subsequent queries to keep your items grouped together, whether saving or retrieving them.
2. Additionally, you can provide other grouping elements such as 'project', 'domain', 'subdomain', 'type', or 'name', whose purpose is to help with organization of settings attached to your key.

To save some setting or a preference: Response will contain a hash key, which you can use for subsequent read/write calls: You can now use that key to read and write additional data. Response: Btw, if you generated a key ahead of time you can certainly just use your existing key instead of receiving a new one. In that case, just add '&key=...' to your /write call.

The API has ability to group or categorize submitted values. It is definitely advisable to somehow group/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. I did not include grouping in the above example to preserve the simplicity of the example, but it is strongly recommended to submit additional parameters with your values such as 'project' for a project name, 'name' to name your data sets, or even if only 'domain' or 'subdomain', which btw refer to subject domains of knowledge (as in Domain Driven Development), not the internet ones. Those are all optional values but they may help tremendously with grouping organizing your data queries later. List of reserved grouping parameters is listed below.

Often it may be necessary to organize your preferences or settings by grouping them according to context, their purpose, or a project.
This would allow to retrieve specific groupings of data as needed. Groupings can be: 'project', 'domain', 'subdomain', 'list', 'type', and 'name'.
All settings are disposable and will be purged after some time of inactivity of the key they are linked with.

The following keywords are reserved. They mostly have to do with organization of the data. The keywords are all very abitrary - they are plain strings, and there is no meaning behind the names, and there is no naming convention. 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	unique key associated with sets of data
hash	same as 'key' above
project	the name of a project
domain	refers to a domain of knowledge rather than the internet domain, but can be used as either
subdomain	similar to 'domain', just another way of grouping elements within a project or a domain
type	the type of the data or project
list	indicates a list type of data organization
name	a name associated with a list or other type of grouping of data

This call will store a setting or a preference in a list called 'my_list' under project 'my_app'. The response will contain a hash (key), which we need to have in order to access the content of the list. We can retrieve the entire list in project 'my_app' with the following call:

Keys expire when they become inactive, meaning they have not been accessed for a period of time with a /read endpoint. When a key hasn't been used in some time, it will have reached its expiration, and so, it will be subsequently deleted from the system and all data associated with that key will be purged as well.

But you don't have to wait for a period of inactivity to purge your data. You can pass in a time-to-live directive with each /write call.
To purge submitted value after N number of minutes, just attach a ...&ttl=N with your /write request.

ttl=<number-of-minutes>

and it will be purged once its time is up. The choice setting below, for user janedoe will be erased after 15 minutes.
Any other values associated with that key will not be affected - unless they also were set with an explicit ttl value. IMPORTANT: TTL parameter is enforced at a value level, it does not purge any other values associated with your key.