exprest

Make easier to build RESTful API based on express-resource

npm install exprest
1 downloads in the last week
4 downloads in the last month

exprest

exprest provides a simple way to build a RESTful API based on express-resource.

Installation

$ npm install exprest

Usage

exprest provides only one function configure().

exprest.configure(app [,opts]);

app must be either express.HTTPServer or express.HTTPSServer, and express-resource must be required() before calling exprest#configure().

The following shows a simple usage of exprest:

var express = require('express')
  , resource = require('express-resource')
  , exprest = require('exprest')
  , app = express.createServer();

exprest.configure(app);

You don't need to write any code for routing. All you have to do is to put a "resource" module, shown as below, in the resources directory under your application root.

module.exports = {
    index: function(req, res) {
      res.end('index');
    }
  , new: function(req, res) {
      res.end('new');
    }
  , create: function(req, res) {
      res.end('create');
    }
  , show: function(req, res) {
      res.end('show');
    }
  , edit: function(req, res) {
      res.end('edit');
    }
  , update: function(req, res) {
      res.end('update');
    }
  , destroy: function(req, res) {
      res.end('destroy');
    }
};

The filename of "resource" module represents the path for that resource. For instance, if you implement a module as resource/users.js, exprest provides routing for /users/*.

Options

You can change configuration of exprest by giving a parameter opts to configure(). If you omit to pass opts, the following object will be applied by default:

{
    basedir: 'resources'
  , root: '/'
  , vars: {}
  , varsKey: 'vars'
  , checkAuth: undefined
  , defaults: {}
}

basedir

Type: String

Directory where "resource" modules are stored.

root

Type: String

Virtual directory for APIs.

Example: { root: '/api' } navigates /api/users/* to resources/users.js.

vars

Type: Object

Variables pass to APIs through http.ServerRequest.

This enables you to share any variables with all "resource" modules. For example, you may call exprest.configure() in app.js and you want to pass a local variable in app.js to "resource" modules. This can be accomplished by using the GLOBAL object, however, most of you prefer to avoid using the GLOBAL, don't you? vars gives you the way to share those variables through http.ServerRequest.

// app.js
var express = require('express')
  , resource = require('express-resource')
  , exprest = require('exprest')
  , mysql = require('mysql').createConnection(...)
  , app = express.createServer();

exprest.configure(app, {
    vars: { mysql: mysql }
});

// resources/users.js
module.exports = {
    index: function(req, res) {
      var mysql = req.vars.mysql; // Passed by exprest
      mysql.query('SELECT * FROM users', function(err, users) {
          ...
      });
    }
};

varsKey

Type: String

Variable name of vars object.

checkAuth

Type: Function

If you provide checkAuth function, exprest calls this function prior to routing, so that exprest provides authentication filter for "resource" APIs. checkAuth must return boolean that indicates if current session is authenticated or not,

If checkAuth returns true, exprest routes to a certain API. If false exprest does nothing. checkAuth must send response to client when it returns false.

A simple example that authentication status stored in session:

var express = require('express')
  , resource = require('express-resource')
  , exprest = require('exprest')
  , app = express.createServer();

exprest.configure(app, {
    checkAuth: function(req, res) {
      if(req.session.user_id) {
        return true;
      }
      res.send(403);
      return false;
    }
});

defaults

Type: Object

Options pass to express-resource.

License

The MIT License

Copyright (c) 2012 Hiromitsu Fujita <bow.fujita@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
npm loves you