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

Features

Pipeline - aerogear.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

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

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" );

Save data - aerogear.pipeline.save( String key, mixed value [, hash options] )

Save data to the server. If this is a new key, the data is created on the server, otherwise, the data on the server is updated.

// Use the tasks pipe created earlier
var myPipe = myPipeline.tasks;

// Store a string
myPipe.save( "key1", "value1" );

// Store an object
myPipe.save( "key2", { val2: "value2" } );

// Pass a set of key/value pairs representing options. In this case, the jQuery.ajax options
myPipe.save( "key3", { val3: "value3" }, {
    ajax: {
        dataType: "json",
        success: function( data, textStatus, jqXHR ) {
            console.log( "Success" );
        },
        error: function( jqXHR, textStatus, errorThrown ) {
            console.log( "Error" );
        }
    }
});

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.

Retrieve data - aerogear.pipeline.read

Retrieve data from the server.

// Use the tasks pipe created earlier
var myPipe = myPipeline.tasks;

// Get a particular item from the server
var val1 = myPipe.read( "key1" );

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

Delete data

Remove data from the server.

// Use the tasks pipe created earlier
var myPipe = myPipeline.tasks;

// Remove a particular item from the server
myPipe.delete( "key1" );

// 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 - Similar to the pipe's save method, 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 maybe "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.

balunasj/persistence-spec.md