Introduction
At its core, the DovetailDB API simply provides a function to insert, update, remove, and
query JSON objects. Your JSON objects are stored in "bag"s. (a bag roughly corresponds to a table
in a relational database) Several bags may exist an a database, and you may create multiple databases
for different projects.
API Example:
// Query string values should be urlencoded, however, for additional
// clarity in these examples, the parameters named "entry" have not been.
// insert some data:
http://dovetaildb.millstonecw.com/insert?db=SocialNet&bag=people&accesskey=XXXXXX&entry={name:'Bob',age:32}
// ... this returns: {"result":"35Wu3GtY6hxkoH1g","version":"1.1"}
http://dovetaildb.millstonecw.com/insert?db=SocialNet&bag=people&accesskey=XXXXXX&entry={name:'Joe',age:21}
// ... this returns: {"result":"zvT_zg6akI1jK-nd","version":"1.1"}
// Find people named Bob that are 18 or over:
http://dovetaildb.millstonecw.com/query?db=SocialNet&bag=people&accesskey=XXXXXX&name_is=Bob&age_min=18
// ... this returns: {"result":[{"name":"Bob","age":32,"id":"35Wu3GtY6hxkoH1g"}],"version":"1.1"}
// Bob has a birthday:
http://dovetaildb.millstonecw.com/update?db=SocialNet&bag=people&accesskey=XXXXXX&id=35Wu3GtY6hxkoH1g&entry={age:33}
// ... this returns: {"result":true,"version":"1.1"}
// Remove Joe:
http://dovetaildb.millstonecw.com/remove?db=SocialNet&bag=people&accesskey=XXXXXX&id=zvT_zg6akI1jK-nd
// ... this returns: {"result":true,"version":"1.1"}
/query
Finds objects in a bag.
&db= (string): The name of the database to query.
&bag= (string): The name of the bag to query within the given database.
&accesskey= (string): The access key given to you.
&*_*= (value): (for instance,
&name_is=)These kind of parameters determine ehich objects to find.
The parameter names should start with a field name to search for, followed by an underscore (_) character,
followed by one of the following suffixes.
Objects that match all the constraints are returned.
Each suffix constrains the named field in a specific manner:
| suffix | possible values | meaning |
|---|
| _is | string,number | The field is equal to the value of this key |
| _in | array | The field is equal one of the values in this array |
| _notin | array | The field is not equal one of the values in this array |
| _min | string,number | The field is greater than or equal to the value of this key |
| _max | string,number | The field is less than or equal to to the value of this key |
| _exclusivemin | string,number | The field is greater than the value of this key |
| _exclusivemax | string,number | The field is less than the value of this key |
&offset= (integer, optional): Start returning results after this many initial results
&limit= (integer, optional): Return at most this number of objects
&sort= (string, optional): Either:
(1) a comma delimeted list of fields, each with an optional direction specifier of "asc" or "desc" (for instance, sort:"age desc, name") -OR-
(2) a server-side Javascript function name prefixed with "fn:" (for instance, sort:"fn:cmpMyObjs").
The function must take two objects to compare and return a value that is less than zero or greater than zero if the first argument should sort after or before the second argument, respectively.
&comet_timeout= (integer, optional): If specified, your query will behave slightly differently. The query will return immediately if there are any available results; however if there are no results, it may wait for results to appear before returning.
Generally speaking, the call will wait up to the specified number of seconds, but it may take longer to return or may return with no results in fewer seconds.
&map= (string, optional): This should be the name of a server-side javascript function that takes a single argument. Each item in the results will be replaced by the return value of this function when given the original result.
&reduce= (string, optional): This should be the name of a server-side javascript function that takes two arguments. This function will be repeatedly applied to items in the result set until there is only a single result, which is subsequently returned.
If a "map" function is also given, that function is applied to each result before reduce is called.
Examples:
// Find people named Bob:
/query?db=SocialNet&bag=people&accesskey=XXXXXX&name_is=Bob
// people named Bob or Joe:
/query?db=SocialNet&bag=people&accesskey=XXXXXX&name_in=%5BBob%2CJoe%5D
// everyone not named Bob:
/query?db=SocialNet&bag=people&accesskey=XXXXXX&name_notin=%5BBob%2CJoe%5D
// everyone 21 or older:
/query?db=SocialNet&bag=people&accesskey=XXXXXX&age_min=21
// everyone ages 16 to 21, but not including 21. (same as 16-20):
/query?db=SocialNet&bag=people&accesskey=XXXXXX&age_min=16&age_max_excl=21
// everyone named Bob that's at least 21 years old:
/query?db=SocialNet&bag=people&accesskey=XXXXXX&age_min=21&name_is=Bob
/insert
Inserts an object into a bag (and assigns it a unique id).
&db= (string): The name of the database to query.
&bag= (string): The name of the bag to query within the given database.
&accesskey= (string): The access key given to you.
&entry= (JSON object, urlencoded): The data to be inserted, expressed as a JSON object, and urlencoded.
Result value: The id of the inserted object.
Examples:
// inserting this object: {name:'Bob',age:32}
/insert?db=SocialNet&bag=people&accesskey=XXXXXX&entry%7Bname%3A'Bob'%2Cage%3A32%7D
// ... this returns: {"result":"JId8Swpp2IMqxI9b","version":"1.1"}
/update
Modifies a persisted object.
&db= (string): The name of the database to query.
&bag= (string): The name of the bag to query within the given database.
&accesskey= (string): The access key given to you.
&id= (string): The id of the object to be modified.
&entry= (JSON object, urlencoded):
This urlencoded JSON object should contain the keys and values to alter on the persisted object.
Properties already defined in the persisted object will not be removed if they are not defined in this
object (the new vales simply overwrite existing ones).
Result value: The JSON "true" value.
Examples:
// Change Bob's are to 30.
/update?db=SocialNet&bag=people&accesskey=XXXXXX&id=JId8Swpp2IMqxI9b&entry=%7Bage%3A30%7D
// ... this returns: {"result":true,"version":"1.1"}
/remove
Deletes a persisted object.
&db= (string): The name of the database to query.
&bag= (string): The name of the bag to query within the given database.
&accesskey= (string): The access key given to you.
&id= (string): The id of the object to be removed.
Result value: The JSON "true" value.
Examples:
// remove Bob
/remove?db=SocialNet&bag=people&accesskey=XXXXXX&id=JId8Swpp2IMqxI9b
// ... this returns: {"result":true,"version":"1.1"}
/call
Invokes a function on the server side and returns the result.
&db= (string): The name of the database to query.
&accesskey= (string): The access key given to you.
&function= (string): The name of the function to call.
&arguments= (array, urlencoded): An array of aguments with which to call the function.
Result value: The value returned by the function.
Examples:
// Supposing we wanted to call myInrementor(1000),
/call?db=SocialNet&accesskey=XXXXXX&function=myIncrementor&arguments=%5B1000%5D
// ... this returns: {"result":1001,"version":"1.1"}
