What?

OpenKeyval lets you store and retrieve data, without any configuration ahead of time.

Why?

The idea here is to provide a data storage system that's as simple to use as humanly possible. We'll keep it safe and fast -- you worry about building something neat.

How do I keep it secure?

OpenKeyval doesn't make any guarantees about security, but you can keep your data relatively private by giving your keys a distinct prefix. Think of it as a sort of password -- instead of saving information at, say, "mydata", save it at "ac75487cc-mydata" or something else equally obscure.

You can also provide read-only access to your data by using the read-only key that is returned with each value that you save.

We also provide a seperate secure (SSL) version of the service, also free.

What's the catch?

There is no catch. There's no sign up, no payment, no hassles. The only limitation is that you can only store up to 64 KiB of data per key.

The API

All of our status responses are given in JSON. Key retrieval is simply returned as raw data.

Store data by POSTing key-value pairs as form data to http://api.openkeyval.org/. We'll respond with a JSON object. If everything goes well, we'll return 'multiset' as the status and an an associative array of keys that were saved as keys. In the keys array, each key you write maps to a read-only version of that key. You can use the either the original key or the read-only version to access the data. The read-only key can be used to give someone access to data without worrying about them modifying it -- it's not possible to figure out what the original key was based on the read-only version.

Store data by POSTing form data to http://api.openkeyval.org/some-arbitrary-key. The value posted as 'data' will be saved to some-arbitrary key. Returns the text 'ok' and an 200 status code on success.

Delete data by posting an empty string as 'data' to the same address. Returns a 200 status code and either 'removed' or 'not-found', depending on whether the value existed.

Fetch data by GETting http://api.openkeyval.org/some-arbitrary-key. Returns the data with a 200 status code on success, or a 404 if not found.

To fetch that data and serve it with an arbitrary MIME type: http://api.openkeyval.org/some-arbitrary-key.image/png

Valid keys

Keys are case-sensitive, and can contain upper and lowercase characters, digits, dashes, and underscores and must be between 5 and 128 characters long.

Valid data

Data is completely freeform and is binary safe. Data size is currently limited to 64 KiB (65,536 bytes).

Examples using openkeyval.js

In addition to the service, we also provide an official JavaScript library, vaguely modeled after HTML5's localStorage. To make use of it, just include the following snippet of code in your page:

<script src="http://cdn.openkeyval.org/statics/openkeyval.packed.js"></script>

This will define an window.remoteStorage object with getItem, setItem, and deleteItem methods. By default, data will be memoized on a per-page basis. To disable this, call OpenKeyval.shouldMemoizeData(false).

Saving a value

This will save the data 'the couch' to the key 'location'. If you'd like to check the result once the save completes, you can pass a callback to this method.

window.remoteStorage.setItem('location', 'the couch', optionalCallbackFunction);

Getting a value

To retrieve the value of the key 'location', call window.remoteStorage.getItem with the key you'd like to retrieve and a callback that will receive the data. Callbacks must be used because data is loaded asynchronously, however, if memoization is on by default, your callback will be called immediately.

var ourCallback = function(value, key) {
  alert('The value of ' + key ' + is ' + value);
};
window.remoteStorage.getItem('location', ourCallback);

Deleting a value

To delete the 'location' key:

window.remoteStorage.deleteItem('location', optionalCallbackFunction);

Examples using cURL

Saving a single value

If we want to save the data 'California' to the key 'location':

$ curl -d "data=California" http://api.openkeyval.org/location

Saving multiple values

If we want to save the data 'California' to the key 'location' and 'Mark' to the key 'username':

$ curl -d "location=California&username=Mark" http://api.openkeyval.org/

Retrieving a value

To read back a value you've already stored:

$ curl http://api.openkeyval.org/location

Serving a file

OpenKeyval lets you serve back data with an arbitrary MIME type (the default is text/plain):

$ curl http://api.openkeyval.org/location.application/octet-stream

Examples using HTML

Sending some data via POST

<form method="POST" action="http://api.openkeyval.org/pianist">
<input type="text" name="data" value="Freddie Mercury">
<input type="submit">
</form>

or, multiple keys:

<form method="POST" action="http://api.openkeyval.org/">
<input type="text" name="location" value="California">
<input type="text" name="username" value="Brian">
<input type="submit">
</form>

Examples using jQuery and JSONP

Because OpenKeyval support JSONP, the normal cross-domain issue with AJAX does not apply. Many JavaScript libraries (such as jQuery) automatically handle JSONP for you.

Getting a value via AJAX

$.ajax({
  url: "http://api.openkeyval.org/location",
  dataType: "jsonp",
  success: function(data){
    alert(data);
  }
});

Setting values via AJAX

The JSONP store module uses a special URI called http://api.openkeyval.org/store/.

$.ajax({
  url: "http://api.openkeyval.org/store/",
  data: "username=Mark&location=California",
  dataType: "jsonp",
  success: function(data){
    alert("Saved "+data);
  }
});

More Features

SSL

To use the SSL version of the site, replace all instances of http://api.openkeyval.org with https://secure.openkeyval.org.

The data stored on the SSL version is completely seperate from the insecure version, to prevent accidental plaintext transfer of secure data.

Open Source

The source code for OpenKeyval is available on github. Contributions are welcome: go ahead and fork the code, make some changes, and send a pull request.

User Contibutions

Bugs / Issues

Please report bugs on the GitHub issue tracker.