Introduction

The Persevere Server handles persistence through a very simple an intuitive JSON REST interface. You can store, retrieve, and modify persisted data using standard REST semantics with the following HTTP methods. The Persevere JavasScript Client communicates through these standard HTTP methods.

GET

The GET method can be used to retrieve an object by id, a value by path, or a result set by JSONPath query. To retrieve an object by id, simply use the url corresponding to the object. For example to retrieve the dyna/0 object:

GET /dyna/0
-->
{"id":"0",
 "name","Root",
...
}

To retrieve a value, simply use property path access appended to a starting id. For example:

GET /dyna/0.name
-->
"Root"

You can use more complex paths:

GET /dyna/0.examples.customers[0]
-->
{"id":"4245",
"lastName":"customer",
"phoneNumber":"a phone?",
"address":"somewhere",
"created":"2007-10-23T14:40:18Z",
"firstName":"first",
"comment":"this is great"
}

You can also use JSONPath queries to retrieve query result sets from the server:

GET /dyna/0.examples.customers[%3F(@.name='first')]
-->
[
{"id":"4245",
"lastName":"customer",
...
}]

POST

You can use the HTTP POST method to append values/rows to existing lists/arrays/tables, by posting to the url for the list object that you want to add to. For example:

POST /dyna/0.examples.customers
{"firstName":"new",
"lastName":"customer"
}

This will add a new customer to the list of customers. If successful, the server will return the newly created object with the newly assigned id:

{"id":"4444",
"firstName":"new",
"lastName":"customer"
}

If the append was not successful, the HTTP status code will indicate the failure

PUT

You can modify an existing object by using PUT method to put a new set of values to existing object id. For example we could modify dyna/4245 with this request:

PUT /dyna/4245
{"id":"4245",
"lastName":"new last name",
...
}

You can also use the PUT method to modify individual property values by using path references. For example we could just change the lastName property of the dyna/4245 by using the following request:

PUT /dyna/4245.lastName
"another new last name"

If the PUT was not successful, the HTTP status code will indicate the failure

DELETE

You can delete existing objects by using the DELETE method with the URL for the object. For example we can delete the dyna/4245 object by this request:

DELETE /dyna/4245

You can also delete a single property by path. For example we could remove the comment property:

DELETE /dyna/4245.comment

If the DELETE was not successful, the HTTP status code will indicate the failure

Object URL Determination

The URL for an object can be determined from the id property by using the standard rules for relative urls. For example if we request:

http://mydomain.com/dyna/0.examples.customers
-->
[
 {"id":"4245",
  "firstName":"first",
...
 }
]

We can determine the URL for the first object from id property (which has a value "4245") in combination with the context of the requested URL (http://mydomain.com/dyna/0.examples.customers). The inferred URL would therefore be http://mydomain.com/dyna/4245.

Referencing

If an object is lazy loaded, circularly referenced, multiply referenced, or on a foreign site, Persevere will use a reference to the object. References are defined as an object with a property "$ref" with a value that represents the id or path of the target object. References follow the same rules as ids for relative URL inference and path resolution. Therefore a reference to an object that has not been transferred in the current response could be denoted:

GET /dyna/4245
-->
{"id":"4245",
 "address":{"$ref":"4250"},
 ...
}

This denotes that the address property should have a value of the object with the id of dyna/4250 (using relative URL inference). A client could do a GET on /dyna/4250 to retrieve this object. Circular reference are also described using references:

{"id":"4245",
 "referenceToSelf":{"$ref":"4245"},
}

References can also have paths in them, which are used by default to reference arrays:

{"id":"4245",
 "myArray":[1,2],
 "duplicateReferenceToMyArray":{"$ref":"4245.myArray"}
}

References can be made to absolute URLs as well:

{"id":"4245",
 "foreignReference":{"$ref":"http://otherdomain.com/obj/1"}
}