Idiot-Simple WEb STorage
iswest API version 1.0

The storage can store and retrieve arbitrary values via alphanumeric
keys, and is subdivided into accounts.  Each account is associated with
a storage namespace.  Identification strings ("IDs") are used for
authorization and authentication purposes.  An account can have one or
more read/write API IDs and zero or more read-only API IDs.   Since each
account has its own namespace, no conflicts can arise between accounts.

There are only three requests: list, get, and put.  Currently only
one request protocol is supported, namely "json", although more can be
added in the future.

A request URI is composed of base URI, the request protocol ("json"),
and the request name (list, get, put).  The request parameters are like
normal form data.  It does not matter to the ISWEST server whether the
request is a POST or a GET.  The request input parameters, as well as
the output of the request are described below in JSON format.
Unrecognized input parameters are silently ignored.

- base URI

For example, http://iswest.tobez.org/iswest.cgi/

- common inputs
	{ jsonp: jsonp-prefix }
	For "json" protocol, if this parameter is present, the returned 
	value is wrapped in parentheses and prefixed with specified
	jsonp-prefix, for JSONP support.  This parameter is ignored for
	other protocols.

- common outputs

	{ error: boolean; error_str: error-description }

Any request can lead to the "error" being set to true with corresponding
error description in "error_str".  If a request succeeds, "error" will
either be undefined or false, meaning that the following test is
sufficient:

	if (result.error) { ... }

Any result should be checked for error being true.

- authentication & authorization

Done by means of IDs.  An ID can be either read-write or read-only.

- request protocol

json/...

- requests

list - list keys
input:
	{ id: ro-or-rw-id; prefix: key-prefix }
	If prefix is absent, lists all keys for this namespace.
output:
	{ keys: [a,b,c] }
	If there are no matching keys, an empty array will
	be returned as the value for "keys".  The "error" will
	NOT be set in such case.

get - fetch data associated with a key
input:
	{ id: ro-or-rw-id; key: key }
output:
	{ data: any-data; last_modified: unix-epoch-timestamp }
	The error WILL be set if there is no such key.

put - store (or delete) data for a key
input:
	{ id: rw-id; key: key; data: any-data }
	An absent data parameter denotes a delete request.
	It is not an error to delete a non-existent key.
output:
	{ ok: boolean }
	If an error occurs, "ok" might not be set at all.
	Normally it is not a problem.

Account management and usage limits.

These are completely external to the protocol.  The service could be
free or paid.  The IDs could be generated with or without e-mail
confirmation.  The limits on the number of keys per account, on the
length of data per key, and/or on the length of the key itself can be in
place.

$Id: api.txt,v 1.8 2006/06/22 19:33:45 tobez Exp $