API helper functions.
npm install rf-apijs
// prepare backend
var config = require('rf-config').init(__dirname); // config
var mongooseMulti = require('mongoose-multi'); // databases
var db = mongooseMulti.start(config.db.urls, config.paths.schemas);
var http = require('rf-http').start({ // webserver
pathsWebserver: config.paths.webserver,
port: config.port
});
// prepare api
var API = require('rf-api').start({app: http.app}); // needs express app
db.global.mongooseConnection.once('open', function () {
// optional: start access control; has to be done before starting the websocket
require('rf-acl').start({
API: API,
db: db,
app: http.app,
sessionSecret: dbSettings.sessionSecret.value
});
`js
// start requests
API.startApiFiles(config.paths.apis, function (startApi) {
startApi(db, API, services);
});
});
`
Usage
`js
// for read only stuff
API.get('funcName', function(req, res) {
// code to process the request here
});
// for read only stuff (GET method required for file download)
API.get('funcName', function (req, res) {
// code to process the request here
}, {realGet: true});
// for stuff with write access
API.post('funcName', function(req, res) {
// code to process the request here
});
`
Technical notes
* we always use "post" in the background, as we can send everything with it without size limit
* there are no url parameters used; the correspondig http Factory transfers a json objects to the API methods; this obj includes everything, we avoid issues with GET method
* in case a GET method is technically required e.g. download a file use "realGet" in API settings
* To avoid collision in namespace between get and post methods name the call on http layer will be completed internally with 'post-' or 'get-'
* name your request properly
req
convert obj structure of original express request
`js
{
session // extracted from rf-acl
token // extracted from rf-acl
user // extracted from rf-acl
rights // extracted from rf-acl
data // data from client
originalRequest // express req
}
`
res
Middleware for express response; adds error handling.
The original express respones is also passed as res.originalResponse
$3
default response function; adds error handling
Example: Simple
`js
res.send(err, data);
`
Example: respond from db with error handling
`js
db.user.groups // send all groups back to client
.find({})
.exec(res.send);
`
Example: using the callback function
`js
createDocs()
function createDocs(){
createDoc(function (err, doc){
res.send(err, docs, processDocs);
})
}
function processDocs(){
console.log(docs)
res.send(err, docs);
}
// linearize asynchron code with the successFunction. instead of:
//
// execute function A
// then execute function B
// afterwards execute function C
// afterwards execute function D
//
// the code is linearized:
//
// execute function A
//
// function A
// then execute function B
//
// function B
// then execute function C
//
// function C
// then execute function D
//
// advantages: better readabilty, automatic error names for each function
`
$3
Send back error with specific error code
`js
res.error("statusRed")
// status 500; standard error; if error isn't handeled
`
`js
res.errorBadRequest("Missing id")
// status 400; missing or wrong parameters
`
`js
res.errorAuthorizationRequired()
// status 401; not autorized for route
`
`js
res.errorAccessDenied("You need be admin")
// status 403; request not allowed for user
`
`js
res.errorNotFound("No user found")
// status 404; not found or not available
`
`js
res.errorAlreadyExists("User exists")
// status 409
`
`js
res.errorNoLongerExists("User is gone")
// status 410; tried to save an entry wich was removed?
`
services
provide plugged in functions from other rf-api-* modules
$3
Example: register functions from other server modules
`js
var Services = API.Services.Services;
function createPdf(url, callback){
createdPdfDoc(url, function(err, pdf){
// callback always has the parameters mongoose like: err, docs
callback(err, pdf)
})
}
Services.register(createPdf)
``