surface v0.8.1
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...
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
8 years ago
8 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago