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.
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 POST
ing 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 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); } });
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
- pyopenkeyval - a Python interface presented as a dict-like object (Marcus Ekelund)
- FlyingV - a Ruby gem for getting and setting values (Tomash)
Bugs / Issues
Please report bugs on the GitHub issue tracker.