kborchers/persistence-spec.md

## persistence-spec.md

      
    Raw
  

              persistence-spec.md
            
          
    Persistence API - draft 0.1

This is a initial proposal on having a very simple persistence layer
Requirements


Enable data to be created/saved/persisted/queryied/removed to/from the server side in a consistent manner without no matter the data format expected by the server

References


API feature inspiration
http://amplifyjs.com/
http://brian.io/lawnchair/
jQuery.ajax

Features

Pipeline

An object representing a collection of server connections and their corresponding models. This object provides a standard way to communicate with the server no matter the data format or transport expected.
Create - aerogear.pipeline( Mixed pipeConfig )

Instantiate aerogear.pipeline. A pipeline must have at least one pipe. Create returns a pipeline object containing methods and pipe objects.


Create a pipeline with a single pipe using the default configuration.
aerogear.pipeline( String pipeName )


Create a pipeline with multiple pipes all using the default configuration.
aerogear.pipeline( Array[String] pipeNames )


Create a pipeline with one or more pipe configuration objects
aerogear.pipeline( Object pipeConfigurations )


The default pipe type is REST. You may also use one of the other provided types or create your own. Pipes may have a number of configuration options. See pipes below.
// Create an instance of aerogear.pipeline with a single pipe
var myPipeline = aerogear.pipeline( "tasks" );

Add pipe - aerogear.pipeline.add( Mixed pipeConfig )

Add another pipe to the pipeline. Add can add pipes using the same options as when the pipeline was created by passing either a single pipe name, and array of pipe names or an object with one or more pipe configurations.
// Add a pipe to the previous created pipeline
myPipeline.add( "tags" );

Retrieve data - aerogear.pipeline.read( [Object requestData] [, function success, function error, function complete] )

Retrieve data from the server.
// Use the tasks pipe created earlier
var myPipe = myPipeline.tasks;

// Get a set of key/value pairs of all data on the server associated with this pipe
var allData = myPipe.read();

// A data object can be passed to filter the data and in the case of REST,
// this object is converted to query string parameters which the server can use.
// The values would be determined by what the server is expecting
var filteredData = myPipe.read({
	limit: 10,
	date: "2012-08-01"
	…
});

Example returned data in allData:
[
	{
		id: 12345
		data: {
			title: "Do Something",
			date: "2012-08-01",
			…
		}
	},
	{
		id: 67890
		data: {
			title: "Do Something Else",
			date: "2012-08-02",
			…
		}
	},
	…
]

Save data - aerogear.pipeline.save( Object data [, function success, function error, function complete] )

Save data to the server. If this is a new object (doesn't have a record identifier provided by the server), the data is created on the server (POST), otherwise, the data on the server is updated (PUT). Any callbacks provided will be used in place of any callback specified in the pipe's configuration.
// Continue use of tasks pipe created earlier
// Store a new task
myPipe.save({
	title: "Created Task",
	date: "2012-07-13",
	…
});

// Pass a success and error callback, in this case using the REST pipe and jQuery.ajax so the funcitons take the same parameters.
myPipe.save({
	title: "Another Created Task",
	date: "2012-07-13",
	…
},
function( data, textStatus, jqXHR ) {
    console.log( "Success" );
},
function( jqXHR, textStatus, errorThrown ) {
    console.log( "Error" );
});

// Update an existing piece of data in the allData var we read earlier
allData[0].data.title = "Updated Task";
myPipe.save( allData[0] );

Save Options

The following items can be passed to the save method as part of a hash of key/value pairs:

ajax - (default: {}) A hash of key/value pairs which can include any option accepeted by the jQuery.ajax method. Some of these options may be ignored or overridden by the selected pipe which will make changes to ensure proper communication with the server. This option is ignored if jQuery.ajax is not used by this pipe type.

Delete data - aerogear.pipeline.delete( [Mixed recordID, function success, function error, function complete] )

Remove data from the server.
// Continue use of tasks pipe created earlier
// Remove a particular item from the server, again from allData created above
myPipe.delete( allData[0].id );

// Delete all data from the server associated with this pipe
myPipe.delete();

Pipes

### REST (Default)
The REST pipe is the default type used when creating a new pipe. It uses jQuery.ajax to communicate with the server. By default, the RESTful endpoint used by this pipe is the app's current context, followed by the pipe name. For example, if the app is running on http://mysite.com/myApp, then a pipe named tasks would use http://mysite.com/myApp/tasks as its REST endpoint.
#### Options
* ajax - A hash of key/value pairs can be supplied to jQuery.ajax method via this option.
* type - This is a string representing the type. Initially, the only option is "REST" which is also the default. Eventually this will include things like "OData" or "WebSocket".
* url - This option can be used to override the default endpoint. A full URL, root relative URL or relative URL may be supplied
New Pipes

TODO: This will explain how to create a new custom pipe rather than just using the provided pipes.