Surface

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...

varsurface=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.0options.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};// orexports.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};// orexports.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 dirctrl: 'controllers',// controllers dirmodel: 'models'// model dirformat: 'json',// format by defaultprefix: 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).aspxoptions: '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_CORSorigin: '*',// 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 urlstatus: 'code',// http status codemessage: 'msg',// http status messagedata: '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