Skip to content

zedgu/surface

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

90 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Surface

NPM version build status Test coverage NPM Monthly Downloads Dependencies License Tips

A tiny middleware of RESTful API for koa.

  • Dependence on koa-ovenware(koa-router).
  • Support both JSON and XML format.
  • Support customize response fields.
  • Support global authentication.
  • Add OPTIONS route for access control(CORS) automatically
  • Write a controller and get all route pattern you want.
  • Compatible with other middlewares including view renders.

Install

npm install surface --save

Simple Usage

####Require...

var surface = require('surface');

####Config...

surface(app);

####Controller file Default path of controllers: ./lib/controllers/

in index.js:

exports.index = function *() {
  this.body = 'hello koa';
};

Checkout the examples.

####Response body Request the root of the app, for example: http://localhost:3000/, will be:

#####in JSON

{
  "request": "/",
  "code": 200,
  "message": "OK",
  "data": "hello koa"
}

#####in XML

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <request>/</request>
  <code>200</code>
  <message>OK</message>
  <data>hello koa</data>
</response>

Conventions

####Action Mapping

route           http method    function of ctrl
:resource       get            index
:resource       post           create
:resource/:id   get            get
:resource/:id   put            update
:resource/:id   del            del

All routes can be customized by setting, see Default values; and also can be changed by controller api singly, see APIs - Routes.

####Resource Resource name will be the file name of the controller, if there is no alias set for the controller, see APIs - Alias.

APIs

####Deprecated

this.wrap // since 0.6.0

options.totally // since 0.6.0

####Options

surface(app[, options])

options see Default values ####Options.authenticate To register a global authentication function. ####Options.deny To set a function to handle the failing authentication.

authenticate and deny have to be Generator Function.

suface(app, {
  /**
   * Global authentication
   * @return {Boolean}
   */
  authenticate: function *() {
    // do something and return true for authenticated, false for denied.
    // this === ctx
  },
  deny: function *() {
    // this.body...
    // this === ctx
  },
  authenticatePattern: /^\/api/i // default to the same as prefixPattern
});

####Controller APIs #####Alias Set alias for the controller.

exports.alias = 'name_you_want';

#####Routes Set routes for the controller.

exports.routes = {
  entry: {
    method: 'get',
    path: '/index'
  }
};

#####Register route directly To register route pattern directly, see koa-router.

app.register('http method', 'name of this route', 'route url pattern', callback);

#####Skip Set true to not format by surface.

ctx.skip_surface = true;

#####Model Get model object.

/**
 * get model object by given controller file name
 *
 * @param   {String}   modelName   optional, undefined for the model has
 *                                 the the same name as this controller
 * @return  {Object}               model object
 */
ctx.model([modelName])
exports.model([modelName])

for exmample:

exports.get = function *() {
  this.model('abc'); // this === ctx
};
// or
exports.todo = function() {
  this.model(); // this === exports
};

#####Ctrl Get controller object.

/**
 * get ctrl object by given controller file name
 *
 * @param   {String}   ctrlName   optional, undefined for self
 * @return  {Object}              ctrl object
 */
ctx.ctrl([ctrlName])
exports.ctrl([ctrlName])

for exmample:

exports.get = function *() {
  this.ctrl(); // this === ctx
  // => return this exports
};
// or
exports.todo = function() {
  this.ctrl('abc'); // this === exports
};

#####Format Get the specifying format

  • by query parameter
  • by header Accept
  • by default setting via options.format

parmeter > Accept > options

Global configuration

####Default values

{
  root: './lib',        // root dir
  ctrl: 'controllers',  // controllers dir
  model: 'models'       // model dir
  format: 'json',       // format by default
  prefix: false,        // true,  only format the route match the prefixPattern;
                        // false, format all routes;
                        // String / RegExp, as the prefix of ALL routes.
                        // When `prefix` is a string / regexp and `options.prefixPattern` is not given, options.prefixPattern =  `new RegExp(prefix)` / `prefix`.
  prefixPattern: /^\/api\/v?\d{1,3}(\.\d{1,3}){0,2}/i,
                        // Only format the route match this pattern. Default to (not setting prefix and prefixPattern by `options`):
                        // /api/v1.1.1/**
                        // /api/0.0.1/**
                        // /api/1/**
  nosniff: true,        // X-Content-Type-Options
                        // see http://msdn.microsoft.com/library/ie/gg622941(v=vs.85).aspx
  options: 'Accept,Content-Type',
                        // false, not add OPTIONS routes for crossing domain requests automatically;
                        // String, to set Access-Control-Allow-Headers;
                        // see https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
  origin: '*',          // false, not add Access-Control-Allow-Origin header automatically;
                        // String, as value of Access-Control-Allow-Origin for all routes;
  authenticate: false,
  fields: {
    path: 'request',    // request url
    status: 'code',     // http status code
    message: 'msg',     // http status message
    data: 'data'        // real data
  },
  aliases: {
    'index': ''
  },
  routes: {
    'index': {
      method: 'get',
      path: ''
    },
    'create': {
      method: 'post',
      path: ''
    },
    'get': {
      method: 'get',
      path: '/:id'
    },
    'update': {
      method: 'put',
      path: '/:id'
    },
    'del': {
      method: 'delete',
      path: '/:id'
    }
  }
}

TODO

  • API Docs

License

MIT

About

A tiny middleware of RESTful API for koa.

Resources

License

Stars

Watchers

Forks

Packages

No packages published