resourced

A resource oriented DSL for configuring express.js (REST).

npm install resourced
56 downloads in the last month

resourced (node.js)

Build Status

NOTE - This is a very early version of this project and is not yet fully featured.

Philosophy

It makes sense to use a general purpose web framework such as express.js for JSON service layers, but when designing such service layers it also makes sense to design in terms of HTTP accessible resources.

If you are familiar with MVC but not REST/ROA then you can think of a resource as serving the same purpose as a controller.

This lightweight DSL thus introduces abstractions that make it easy to design in a resource-oriented (RESTful) style. Each resource contains:

  • URL - The address of the resource.
  • Methods - One or more HTTP request handler methods.
  • Caching - Where and how long to cache responses from the resource (optional).
  • Middleware - Middleware to run before and after requests, for example to perform authorization (optional).

Features

  • Request Handlers - Features like argument population make handling requests easier.
  • Caching - HTTP caching of responses to GET requests.
  • Validation - Allows validation of request bodies and URL's.
  • Conventions - Conventions are included to make it easier to create HTTP friendly services.

Samples

The sampl is taken from the example application.

Configuration

To configure restless you need to tell it which directory to look for resources in:

var resourcesDirectory = __dirname + '/resources';
resourced.configureResourcesInDirectory(resourcesDirectory, done);

The directory will be scanned for files including resources. You must also tell express to use the body parser:

app.use(express.bodyParser())

Resource Definition - JavaScript

The following shows a simple person resource, where the JSON response includes a link to the associated address:

var Resource = require('resourced').Resource
    http = require('resourced').http,
    cache = require('resourced').cache;

module.exports = new Resource({
    url: "/people/:id",

    cache: cache.minutes(5).publically(),

    respondsTo: [
        // NOTE - Here instead of using http.get we could have used an anonymous object with
        // a property called get containing the function, as we've done for PUT below.
        http.get(function(id) {
            return {
                firstName : "Colin",
                secondName : "Jack",
                id : id,
                address: address: this.urlFor(addressResource, {id: 5})
            };
        }),

        { 
            put: function(id, body) {
                return body;
            }
        }
    ]
});

The response to a GET request for the associated URI (for example /people/5) would be:

HTTP/1.1 200 OK
X-Powered-By: Express
Cache-Control: max-age=300, public
Content-Type: application/json; charset=utf-8
Content-Length: 129
...
{
  "firstName": "Colin",
  "secondName": "Jack",
  "id": "5",
  "address": {
    "rel": "address",
    "url": "/address/5"
  }
}

Note the link to the associated address in the response.

Running Examples

You can run the sample application using the following command:

node examples/web.js

The output will end with a hard-coded URL that you can use to interact with the first resource using curl:

GET curl http://localhost:3050/people/5
PUT curl -i -H "Content-Type: application/json" -X PUT 'http://localhost:3050/people/5' -d '{"firstName":"Mighty"}'
POST curl -i -X DELETE 'http://localhost:3050/people/5'
DELETE curl -i -X POST 'http://localhost:3050/people/5'

Running Tests

The tests use mocha so you first need to install it:

npm install -g mocha

You can then run the tests using npm test.

npm loves you