HTTP API Reference

DovetailDB API Reference

This is the reference document for DovetailDB's HTTP API.

One primary use case for DovetailDB is to run as a JSONP server; therefore, the API is not at all RESTful. It should instead be viewed as a RPC service routed over HTTP. If you are accessing DovetailDB with GET requests, you will need to append globally unique identifiers to all calls to avoid intermediate systems caching your requests (javascript libraries like JQuery will do this for you automatically). If you're in an environment where you are able to POST, you should POST all requests.

query
put
remove
call
execute

Introduction

At its core, the DovetailDB API simply provides a function to put, 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 carrying JSON should be urlencoded. For additional clarity
// in these examples, such parameters have been left in their pre-urlencoded form.

// insert some data:

http://dovetaildb.millstonecw.com:19156/sandbox/put?bag=people&entry={"name":"Bob","age":32,"id":"P001"}
// ... this returns:   {"result":null,"version":"1.1"}
http://dovetaildb.millstonecw.com:19156/sandbox/put?bag=people&entry={"name":"Joe","age":21,"id":"P002"}
// ... this returns:   {"result":null,"version":"1.1"}

// Find people named Bob that are 18 or over:

http://dovetaildb.millstonecw.com:19156/sandbox/query?bag=people&query={"name":"Bob","age":[">=",18]}
// ... this returns:   {"result":[{"name":"Bob","age":32,"id":"P001"}],"version":"1.1"}

// Bob has another birthday:

http://dovetaildb.millstonecw.com:19156/sandbox/put?bag=people&entry={"id":"P001","age":33,"name":"Bob"}
// ... this returns:   {"result":null,"version":"1.1"}

// Remove Joe:

http://dovetaildb.millstonecw.com:19156/sandbox/remove?bag=people&id=P002
// ... this returns:   {"result":null,"version":"1.1"}

query

Finds objects in a bag.

&bag= (string): The name of the bag to query within the given database.

&query= (value): A pattern used to select results. Patterns are JSON structures, often resembling the desired result(s):

JSON type	JSON value	meaning
string		Matches exactly this string
number		Matches exactly this number
null		Matches a null value
object	{.., <keyN>:<patternN>, ..}	Matches any JSON object for which every <keyN> is defined and has a value that matches the corresponding <patternN>. (therefore, the empty object pattern, "{}", matches any object)
array	['\|', [.., <patternN>, ..]]	Matches if the value matches at least one <patternN>
array	['&', [.., <patternN>, ..]]	Matches if the value matches every <patternN>
array	['!', <pattern>]	Matches if the value does not match <pattern>
array	['>', <threshold>]	Matches if the value is greater than <threshold>
array	['<', <threshold>]	Matches if the value is less than <threshold>
array	['>=', <threshold>]	Matches if the value is greater than or equal to <threshold>
array	['>=', <threshold>]	Matches if the value is less than or equal to the <threshold>
array	['()', <minvalue>, <maxvalue>]	Matches if the value is between <minvalue> and <maxvalue>, exclusive
array	['[]', <minvalue>, <maxvalue>]	Matches if the value is between <minvalue> and <maxvalue>, inclusive
array	['(]', <minvalue>, <maxvalue>]	Matches if the value is between <minvalue> and <maxvalue>, including <maxvalue> but not <minvalue>
array	['[)', <minvalue>, <maxvalue>]	Matches if the value is between <minvalue> and <maxvalue>, including <minvalue> but not <maxvalue>
array	['*']	Matches any value
array	[<pattern>]	Matches an array where <pattern> matches the union of values under it**

&offset= (integer, optional): Start returning results after this many initial results

&limit= (integer, optional): Return at most this number of objects

&score= (object, optional): A JSON object representing a scoring pattern:

JSON type	JSON value	meaning
object	{.., <keyN>:<patternN>, ..}	Score is the sum of the scores produced by each scoring <patternN> applied to the corresponding sub-value, or applied to null if the value is not an object or does not have <keyN> defined. If any sub-result is non-scoring, this is also non-scoring.
array	["NumericScore", <default score>, <lower bound>, <upper bound>*]	If the value is a number and it is inside the bounds (if specified), then the score is equal to that value. Otherwise, if the <default score> was specified, it is returned. If no <default score> was specified, the result is non-scoring.
array	["ReverseScore", <pattern>]	Returns the inverse score produced by <pattern> (as if it were multiplied by -1)
array	["MultipliedScore", <multiplier>, <pattern>]	Returns the score produced by <pattern> multiplied by <multiplier>
array	["LookupTableScore", [.., [<keyN>,<scoreN>], ..], <default score>*]	If the value is equal to some <keyN>, then <scoreN> is returned. <keyN>s must be strings or numbers, and may not be repeated. If no match is found, the result is equal to the <default score>, or is non-scoring if no default was specified.
array	["LinearlyInterpolatedScore", [.., [<keyN>,<scoreN>], ..], <default score>*	<keyN>s must be numbers and they must appear in sorted order. The score returned is linearly interpolated between the scores of the two nearest <keyN> values. If the value falls outside the covered range, the score of the nearest endpoint is selected. If the value is not a number, the result is equal to the <default score>, or is non-scoring if no default was specified.
<any other>		Not a valid scoring pattern

Examples:

// Find people named Bob:
/sandbox/query?bag=people&query={"name":"Bob"}

// people named Bob or Joe:
/sandbox/query?bag=people&query={"name":["|",["Bob","Joe"]]}

// everyone not named Bob:
/sandbox/query?bag=people&query={"name":["!", "Bob"]}

// everyone 21 or older:
/sandbox/query?bag=people&query={"age":[">=", 21]}

// everyone aged 16 to 21, but not including 21.
/sandbox/query?bag=people&query={"age":["[)", 16, 21]}

// everyone named Bob that's at least 21 years old:
/sandbox/query?bag=people&query={"age":[">=",21], "name":"Bob"}

put

Inserts an object into a bag. If an object already exists with the given "id", it is overwritten.

&bag= (string): The name of the bag to update within the given database.

&entry= (JSON object, urlencoded): The data to be inserted, expressed as a JSON object, and urlencoded.

Examples:

// inserting this object: {name:'Bob',age:32}

/sandbox/put?bag=people&entry={"name":"Bob","age":32","id":"JId8Swpp2IMqxI9b"}

// ... this returns:   {"result":null,"version":"1.1"}

remove

Deletes a persisted object.

&bag= (string): The name of the bag to update within the given database.

&id= (string): The id of the object to be removed.

Result value: null

Examples:

// remove Bob

/sandbox/remove?bag=people&id=P001

// ... this returns:   {"result":null,"version":"1.1"}

call

Invokes a function on the server side and returns the result.

&function= (string): The name of the function to call. It must be defined at the top level of some code file registered with the database.

&arguments= (JSON array, urlencoded): An array of aguments with which to call the function.

Result value: The value returned by the function.

Examples:

// Suppose we wanted to call a function defined in the sandbox database that adds two numbers

/sandbox/call?function=add&args=[3,4]

// ... this returns:   {"result":7.0,"version":"1.1"}

execute

Execute an arbitrary script expression on the server.

&code= (string): The script expression to execute.

Result value: The value returned by the expression.

Examples:

// Suppose we wanted to add two numbers:

/sandbox/execute?code=3-1

// ... this returns:   {"result":2.0,"version":"1.1"}