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 = ;
Config...
;
Controller file
Default path of controllers: ./lib/controllers/
in index.js:
exports { thisbody = 'hello koa';};
Checkout the examples.
Response body
Request the root of the app, for example: http://localhost:3000/, will be:
in JSON
in XML
/ 200 OK hello koa
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
thiswrap // since 0.6.0 optionstotally // since 0.6.0
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
.
;
Controller APIs
Alias
Set alias for the controller.
exportsalias = 'name_you_want';
Routes
Set routes for the controller.
exportsroutes = entry: method: 'get' path: '/index' ;
Register route directly
To register route pattern directly, see koa-router.
app;
Skip
Set true to not format by surface.
ctxskip_surface = true;
Model
Get model object.
/** * get model object by given controller file name * * @param * the the same name as this controller * @return */ctxexports
for exmample:
exports { this; // this === ctx};// orexports { this; // this === exports};
Ctrl
Get controller object.
/** * get ctrl object by given controller file name * * @param * @return */ctxexports
for exmample:
exports { this; // this === ctx // => return this exports};// orexports { this; // 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}{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