Rf-api NPM | npm.io

Rapidfacture API

Express Middleware with plugin system that reduces bad code practices

shortens code
prevent forgotten error handling
uniform error messages
linearize asynchron code

Plugins

Install

To install the module:

npm install rf-api

// 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);
 });
});

@desc
Calls API functions defined in server api files

@example
// Integration in module.exports.API
api(functionName, func, settings, 'post', this);


@param functionName Function name defined in API, e.g. 'order-update'

@param func Function to be executed, defined in API

@param settings Options how to handle endpoint, defined in API

@param method String containing 'realGet' / 'get' / 'post' to get settings from getOptions function

@param self Object module.exports.API, always called with 'this'



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

res.send()

default response function; adds error handling

Example: Simple

res.send(err, data);

Example: respond from db with error handling

db.user.groups  // send all groups back to client
  .find({})
  .exec(res.send);

Example: using the callback function

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

res.errors

Send back error with specific error code

res.error("statusRed")
// status 500; standard error; if error isn't handeled

res.errorBadRequest("Missing id")
// status 400; missing or wrong parameters

res.errorAuthorizationRequired()
// status 401; not autorized for route

res.errorAccessDenied("You need be admin")
// status 403; request not allowed for user

res.errorNotFound("No user found")
// status 404; not found or not available

res.errorAlreadyExists("User exists")
// status 409

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

Register functions

Example: register functions from other server modules

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)