deep-restful

Homogeneous Restful collection manipulation for deepjs.

This library comes with :

• a memory Collection manager that define exactly the same API than any other deepjs client.
• a memory Object manager that define the same API
• a HTTP/Restful client that define the same API and used as base class for other deepjs http clients (jquery ajax, nodejs http, etc.).
• other stores related sheets (transformations applied on stores that gives homogeneity)
• a chained, Promise based, restful handler that use this API and allow dependency injection.

The API defines :

• get("id" || "?myQuery=true" || "")
• range(start, end, query)
• post( obj || null )
• put( obj || null )
• patch( obj || null )
• del( obj || null )
• rpc( method, args, id)
• bulk( actions )

And defines additionnaly for collections (not for deep.Object)

• flush()
• count()

It could be combined with protocols and OCM. (see deepjs core docs for more infos).

install

npm install deep-restful

or

bower install deep-restful

It will install also deepjs if not already there.

Simple usage

var deep = require("deepjs/deep"); // load core
require("deep-restful/index");  // load chain
require("deep-restful/lib/collection"); // load collection manager
 
new deep.Collection("myProtocol", [{ id:"e1", title:"hello world"}]);
 
deep.restful("myProtocol")
.get("e1")
.done(function(obj){
    // do something with obj
    obj.title = "hello deep-restful";
})
.put()
.log(); // you'll se the putted object

JSON-Schema validation :

You could associate a schema to a collection :

var deep = require("deepjs/deep"); // load core
require("deep-restful/index");  // load chain
require("deep-restful/lib/collection"); // load collection manager
 
new deep.Collection({ 
    protocol:"myProtocol", 
    collection:[{ id:"e1", title:"hello world"}],
    schema:{
        properties:{
            title:{ type:"string", required:true, minlength:6 }
        }
    }
);
 
deep.restful("myProtocol")
.get("e1")
.done(function(obj){
    // do something with obj
    obj.title = "hello";
})
.put()
.log(); // you'll see an error 412 PreconditionFail with a report describing the validation error.

Constraints

Within the JSON-Schema, you could define constraints on any properties :

• private : property is removed on "get" (query and range also)
• readOnly : property could not be modified

There is a more obstrusive constraint that allow to securise collection access by item's owner. (it work with session defined in deep.context : see autobahnjs)

• ownRestriction : could be a string, giving the name of the property in item that give owner (as "userId"), or false.

And finally, collection managers could apply transformation automatically on post/put/patch, wich is usefull for hashing a password on update by example.

var deep = require("deepjs/deep"); // load core
require("deep-restful/index");  // load chain
require("deep-restful/lib/collection"); // load collection manager
 
 
var myCollection = new deep.Collection({ 
    protocol:"myProtocol", 
    collection:[{ id:"e1", title:"hello world"}],
    schema:{
        properties:{
            password:{
                type:"string", 
                required:true, 
                minlength:6,
                "private":true
                transform:[function(input){ return deep.utils.Hash(input); }] 
            },
            email:{ type:"string", format:"email", readOnly:true }
        }
    }
);
 
deep.restful(myCollection)
post({
    password:"test1234", // password will be hashed
    email:"[e-mail]"
})
.slog() // you see the posted result : without password
.done(function(obj){
    obj.email = "johnny#begood.com";
})
.patch()
.log(); // you'll see an error 412 PreconditionFail : email is readonly

JSON-RPC

You could include RPC methods in you store definition.

var deep = require("deepjs/deep"); // load core
require("deep-restful/index");  // load chain
require("deep-restful/lib/collection"); // load collection manager
 
 
new deep.Collection({ 
    protocol:"myProtocol", 
    collection:[{ id:"e1", title:"hello world"}],
    methods:{
        addDescription:function(handler, description){
            // 'this" refer to object retrieved with id provided to rpc call
            this.description = description;
            this.lastUpdate = +new Date;
            return handler.save();
        }
    }
);
 
deep.restful("myProtocol")
rpc("addDescription", ["object's description"], "e1")
.slog() // you see the rpc result
.get() // get all on current store
.log(); // you see an array : [{ id:"e1", title:"hello world", "object's description"}]

Other Collection clients

Persistent Collection

You could use deep-mongo or deep-local-storage (among other) to have persistent collection that implement same API than above.

example with deep-mongo :

var deep = require("deepjs"); // load core
require("deep-restful");  // load chain
require("deep-mongo"); // load driver
 
deep.Mongo({ 
    protocol:"myProtocol", 
    collectionName:"myCollection",
    url:"mongodb://127.0.0.1:27017/test",
    schema:{
        properties:{
            title:{ type:"string", required:true, minLength:6 }
        }
    },
    methods:{
        //...
    }
);
 
deep.restful("myProtocol")
.get("e1")
.done(function(obj){
    // do something with obj
    obj.title = "hello mongodb";
})
.put()
.log(); // you'll see the putted object

HTTP/Restful client

When you want to interact with remote restful services (from browser or nodejs to remote server), you could use http clients such as 'deep-jquery/ajax/xxx' or 'deep-node/rest/http/xxx' where xxx=json|html|xml that implement same API than above but act remotely.

var deep = require("deepjs"); // load core
require("deep-restful");  // load restful chain
require("deep-jquery/ajax/json"); // load json restful client
 
// define a json client to your remote json service
deep.jquery.ajax.json({ 
    protocol:"myService", 
    baseURI:"/my/service/base/uri"
});
 
deep.restful("myService")
.get("....") // get something from remote service. e.g. from : /my/service/base/uri/....
.done(function(obj){
    // do something with obj
})
.put()
.log(); // you'll see the put result on remote service or any error from chain.

When you use your service through deep.restful chain and protocols, you don't even need to know if you're working remotely or not. Code still the same.

It acts as a dependecy injection mecanism and allows great modularity and isomorphism.

You could develop then all your services and clients logics blindly browser side or server side (or from deep-shell), with dummies collections or not, and then choose to run it remotely or not, with different stores implementations depending on production flags by example.

Remote and local validation

When you want to pre-validate datas before to send them to remote services (by example on form submition from browser), you could specify in your remote client definition where to get schema before sending datas to remote (or you could provide directly your own schema).

var deep = require("deepjs"); // load core
require("deep-restful");  // load restful chain
require("deep-jquery/ajax/json"); // load json restful client
 
// define generic json client
deep.jquery.ajax.json("json");
 
// define a json client to your remote json service
deep.jquery.ajax.json({ 
    protocol:"myService", 
    baseURI:"/my/service/base/uri",
    schema:"json::/my/service/base/uri/schema"
});
 
deep.restful("myService")
.get("....") // get something from remote service. e.g. from : /my/service/base/uri/....
.done(function(obj){
    // do something with obj
})
.put() // will pre-validate with local schema before send
.log(); // you'll see the put result on remote service or any error from chain (maybe a precondition fail from local validation).

Remarque : If the remote service is defined with a deep-restful compliant store (with autobahnjs by example), and if it has a schema defined, you could retrieve it by passing "schema" as id. e.g. deep.get("myService::schema").log(); or deep.restful("myService").get("schema").log();.

Nodejs simple example

 
var http = require('http');
var deep = require('deepjs'); // the core
require('deep-restful'); // homogeneous restful API
require('deep-restful/lib/collection'); // simple memory collection
 
new deep.Collection("myobjects", []);
 
var titles = ["hello", "deepjs", "world"];
var count = 0;
 
http.createServer(function (req, response) {
    deep
    .restful("myobjects")
    .post({ title:titles[++count%3], count:count })
    .get(String(req.url).substring(1))
    .done(function(res){
        response.writeHead(200, {'Content-Type': 'application/json'});
        response.end(JSON.stringify(res));
    })
    .fail(function(error){
        console.log("error : ", error.toString());
        response.writeHead(error.status || 500, {'Content-Type': 'application/json'});
        response.end(JSON.stringify(error));
    });
})
.listen(1337, '127.0.0.1');
 
console.log('Server running at http://127.0.0.1:1337/');
 

Then, open your browser, go to http://127.0.0.1:1337/, refresh few times, and try :

http://127.0.0.1:1337/an_id_of_an_item_in_collection or http://127.0.0.1:1337/?title=deepjs or http://127.0.0.1:1337/?count=lt=2

Licence

LGPL 3.0