A tiny middleware of RESTful API for koa.
- Dependence on koa-router.
- Support both JSON and XML format.
- Support customize response fields.
- Write a controller and get all route pattern you want.
- Compatible with other middlewares including view renders.
npm isntall surface --save####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>####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.
####Options
surface(app[, options])options see Default values
####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'
}
};#####Wrap Set false to not format by surface.
ctx.wrap = false;#####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 *(next) {
this.model(); // this === ctx
yield next;
};
// or
exports.todo = function() {
this.model(); // this === exports
};#####Format Get the specifying format
- by query parameter
- by header
Accept - by default setting via options.format
parmeter > Accept > options
####Default values
{
root: './lib', // root dir
ctrl: 'controllers', // controllers dir
model: 'models' // model dir
format: 'json', // format by default
totally: true, // true, format all routes;
// false, only routes setting by controllers.
nosniff: true, // X-Content-Type-Options
// see http://msdn.microsoft.com/library/ie/gg622941(v=vs.85).aspx
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: 'del',
path: '/:id'
}
}
}MIT