Percolator is an opinionated web framework for writing RESTful JSON APIs in node.js.

It makes APIs much less tedious to write than many other modern-day frameworks, and it makes APIs that are generally nicer to use than many other modern day "REST" APIs.

Features:

It does NOT:

Hello World!

If you have a server.js with the following content...

var Percolator = require('Percolator').Percolator;
var server = new Percolator();
server.route('/', function(req, res){
        res.object({hello : "world!"})
             .send();
          });
server.listen(function(err){
    if (err) { throw err; }
    console.log("Percolator is listening on port ", server.port);
});
... you can run it with node server.js and it should tell you:

Percolator is listening on port 3000

If you hit http://localhost:3000/ , you will see:

{

    "hello": "world!",
    "_links": {
        "self": {
            "href": "http://localhost:3000/"
        }
    }

}

What the @#$%&* is that?!?!?

One of the core features of Percolator is that it helps you make your API "surfable" by helping you add links that allow you and your users to actually surf your API to see all the possible uses and capabilities without you having to write a million pages of documentation, and without asking your users to read it (Note: There are other possibly more important benefits as well, but I'll save that more in-depth discussion for another time). In my experience, these are the kinds of APIs that users (including the original developers!) actually enjoy using.

The interesting parts of this example are probably all in the routing and request handling. Let's take a second look at that:

server.route('/', function(req, res){
            res.object({hello : "world!"})
             .send();
          });

server.route() takes a route, in this case the root route '/', and associates a handler to it for when a request comes in for '/'. If the handler is just a function, as is the case here, then it will only handle GET requests.

This just scratches the surface though. Other examples will show more advanced features.

Values

Make the hard stuff simple

Make the tedious stuff less tedious

Keep the simple stuff simple

Focus on helping create great APIs