Every ExpressHappiness project consists of a specific set of files that define the project's routes and behaviour.
These files are:
Routes Tree Configuration: On this file you'll put / define all
of the supported routes of your app with all of their details. These details include the method of the route
(get / post / put / delete), the parameters of the route (parameter type, validation rules) and you can also enable / disable
the mock operation.
For each route you can define an alias name and also the group(s) that this route belongs to. The "groups" that the
routes belong to are custom groups, with custom names. The groups that a route belongs to define the middlewares that
will be applied to it. More details about grouping and group-specific middlewares will be defined later on.
Reusable Params File: There are cases where many routes have the exact same parameter, with the
exact same type and validation rules. In order to avoid rewriting the same parameter definition again and
again throughout all of these routes you can define these params once and just reuse them to any of the routes. The file
that holds the "reusable params" definitions is the Reusable Params File.
These type of parameters are called "reusable" params and are defined on the Reusable Fields File
Error Handling Configuration File: At any point of the middlewares chain of any call you can
trigger errors. Errors of custom types, decorated with custom details. Express Happiness provides an error handling
mechanism that automatically takes care this errors. The way each custom type's error will be handled is defined on this file.
The developer has the ability to define whether and what is going to be written to the error.log file,
what code should be sent back to the client (200, 400, 401, etc) and what data will be served. Finally, on each of these
error types, the developers can define a set of hook functions to be executed (email send, log to db, whatever).
All these error handling parameters are defined on the Error Handling Configuration File.
error log: Is just a plain text file holding all logs printed out by the Error Handling mechanism
Controller Functions: This file defines the function that should be executed on each route.
The main concept here is not to define / write the body of these functions within this file but to have a "mapper"
endpoint though which anyone can easily find out what's going on, on any route.
The association between routes and controller functions is done by an associative array,
each key of which is a string, either the full route definition or the route alias and each value the corresponding controller function.
As mentioned, routes' aliases can be defined on the Routes Tree Configuration File.
Starting with it
In order to start, you can just clone this repo to your machine or either follow step
by step this document.
Create your Reusable Params File
Each route expects for some params to be passed on call. As mentioned, Express Happiness includes an automatic params
validation mechanism and the only thing you should do is to define the params and the validation rules that apply for
each route.
Each parameter, no matter its type, has the following structure:
Code Snippet 1. Parameter's basic structure
param: {
"key": "the-key-name",
"type": "one-of-the-supported-types",
"humanReadable": "short title of the param",
"description": "A human-readable description of the parameter",
"mandatory": "boolean-true-or-false"
}
Not all of these characteristics are mandatory nor are they all. For each parameter type, special characteristics apply.
For example, for type "int", the definition object of the param may (optionally) include "min" and "max" keys, etc.
The list of the supported parameter types is:
Table 1. Supported parameter types
int
Integer
date
Date
oneof
The value must be one of the specified
boolean
Boolean
numeric
any number
string
String
array
Array
object
Object
The full list of the supported attributes for each param are listed below:
Table 2. Supported param attrs
Attribute key
Mandatory
Description
Applies to
key
yes
the key name of the parameter. For example, if on a route you expect for a param with the name "x", then the key
of this param is "x"
all types
type
yes
the type of the parameter. Might be one of: "int", "date", "oneof", "boolean", "numeric", "string", "array" and "object"
humanReadable
no
a short title of the parameter. This is used by the parameters validator on the error texts that exports on validation failures
all types
description
no
the description of the parameter. It will be used on the auto-generated documentation of your API
all types
mandatory
no
defines whether the parameter is mandatory or not. If it's missing the parameter is not mandatory
all types
validationFailureTexts
no
An object containing the text messages that will sent back to the client for all (or any) cases that the validation fails. For example,
if a mandatory field is missing the text that will be sent back to the client is defined on the key "mandatory" of this object, etc. The
supported keys of this object are listed on the very next table that follows.
all types
min
no
the minimum value (including this) that a param can accept
int, numeric
max
no
the maximum value (including this) that a param can accept
int, numeric
minChars
no
the minimum characters that a string's type parameter's value might have
string
maxChars
no
the maximum characters that a string's type parameter's value might have
string
validationString
yes
the format that a date value should have. The formats are identical as on moment.js
date
minLength
no
the minimum length an array-type value should have
array
maxLength
no
the maximum length an array-type value should have
array
acceptedValues
yes
an array listing all the acceptable values for this param
oneof
regexp
no
a regular expression to check the provided value against
string
keys
no
an object that specifies the expected structure of an object type parameter
object
The supported keys of the validationFailureTexts are:
the type of the field's value is not of the defined/expected field's type
mandatory
a mandatory filed is missing
min
the either of type int or numeric field's value is lower than the minimum accepted, according to the min attribute of the field's definition
max
the either of type int or numeric field's value is greater than the maximum accepted, according to the max attribute of the field's definition
minChars
the characters of the provided string are less than the minimum accepted, according to the minChars attribute of the field's definition
maxChars
the characters of the provided string are more than the maximum accepted, according to the maxChars attribute of the field's definition
validationString
the value provided for the field of type date is not compatible with the validationString of the field's definition
minLength
the length of the array passed on the specific field's value is lower than the minimum accepted, according to the minLength attribute of the field's definition
maxLength
the length of the array passed on the specific field's value is greater than the maximum accepted, according to the maxLength attribute of the field's definition
acceptedValues
the value of the, of type oneof, field is not present on the acceptedValues array on the field's definition
regexp
the string provided does not comply with the regular expression from the regexp property of the field's definition
So, as an example:
Code Snippet 2. Parameter's structure including validationFailureTexts object
param: {
"key": "user_age",
"type": "int",
"humanReadable": "Age",
"description": "The age of the user",
"mandatory": "true",
"min": 18,
"validationFailureTexts": {
"mandatory": "Please provide your age",
"min": "Sorry, you must be at least 18 years old"
}
}
In such case if the submitted value for the "age" is under 18 (let's say 17) then on the "errors" array of the response there will be the
text "Sorry, you must be at least 18 years old". If the key "min" was missing from the "validationFailureTexts" object (of if
the "validationFailureTexts" was missing at all on the field's definition), the error text that would be included on the errors array would be the default:
"Age must be greater or equal to 18. 17 provided."
Finally, in the case that there was the "humanReadable" key missing from the field's definition, then the error text would be:
"user_age must be greater or equal to 18. 17 provided."
Now it's time to proceed with your Reusable Params File.
The reusable params file is just a module that exports an object. This object has a number of keys. Each
key holds another object which represents the definition of a parameter.
The name of the key is the way you'll refer to the parameter from the Routes Tree Configuration File.
So, let's assume that you want to define two reusable parameters on this file, parameter "id" and parameter
"cat_id". Here's a possible / valid definition of these two params in the Reusable Params File:
Code Snippet 3. Example of Reusable Params File
module.exports = {
id:{
key:'id',
type:'int',
humanReadable: 'organization id',
description:'The Organization from which data is requested',
mandatory:true
},
category: {
key:'cat_id',
type:'oneof',
humanReadable: 'Product category',
description:'The category of the product',
mandatory:false,
acceptedValues: ['shoes', 'clothes'],
validationFailureTexts: {
acceptedValues: 'Sorry, only shoes or clothes categories are supported'
}
}
}
Pay attention that we have a unique name for each parameter defined here, which is the key of the
exported module. This name will be used in the Routes Tree Configuration File in order to load and
define the parameters that each route will expect for.
Though, each of these params have a "key" attribute. This is the name of the parameter as we expect it
during the actual calls that our service will receive.
Defining object type params
As mentioned, one of the supported param types is the "object". Also, one of the supported on object-type parameter's attributes
is "keys".
You can use the "keys" attribute of an object parameter in order to define (to any depth) the expected structure of the object
and not only this. You can apply / define validation rules of each of them, no matter which depth it is. Here's an example:
Let's suppose that on a specific call we expect for a parameter with the name "user_data" which will hold the user's information
in a well defined structure. Both the structure of the expected object and the validation rules that apply to it are made
obvious through the following parameter definition:
Code Snippet 4. Example of an object parameter
user:{
key:'user_data',
type:'object',
humanReadable:'User data',
description:'Full user information',
mandatory:true,
keys:{
gender:{
type:'oneof',
mandatory:true,
acceptedValues: ['male', 'female'],
validationFailureTexts: {
mandatory: 'Please specify your gender',
acceptedValues: 'Please pick between male and female'
}
},
country:{
type:'oneof',
acceptedValues:['Greece', 'Sweden', 'Australia', 'Romania']
},
name:{
type:'object',
keys:{
first:{
mandatory:true,
type:'string'
},
last:{
mandatory:true,
type:'string',
validationFailureTexts: {
mandatory: 'Please specify your last name'
}
},
middle: {
mandatory: false,
type: 'string'
}
}
}
}
}
So, as you can see, not only we define the structure of the expected object but we can define the validation rules that might
apply to any of the keys of the object. Please mention that the "name" key is an object itself and it also contains the "keys"
parameter which holds the information regarding the expected keys of it. There's no limit on the depth of the nested objects
and parameters.
The "keys" param is an object which holds a set of keys. These keys represent / map the expected keys of the object.
The attributes of each one of these keys are identical with the attributes used in plain (not-object) parameters. All attributes
of table 2 apply just fine to all nested keys of all objects. The only difference between the definition of a plain parameter
and the definition of an object's key is that on the object key's definition there's no "key" attribute. The "key", that is
the expected name of the key on the provided object during a call, is identical to the name of the key itself. E.g. on the
specific example we expect the user_data.name.first to be present.
This has been implemented this way for two reasons:
There's no need and no way to refer to a nested key from services such as the FieldsLoader (we'll see about that later on)
We wanted to mimic the structure of the object in an one-to-one mapping
During the parameters validation process, which we'll analyse on following chapter, the full object is been validated according
to the definition of it. Don't worry this process is 100% asynchronous, so you can go ahead and create as deep, as long and
as complex object parameter definitions. It won't block your app during validation.
Routes Tree Configuration File
Now that we've defined the parameters that we're going to (re)use on our endpoints, it's time to define
these calls. Of course you can always come back to the Reusable Params File and update it with new
ones.
All of the supported routes of our application are defined in this very file.
In order to be able to reuse the parameters we defined in the Reusable Params File, we need the (built in) FieldsLoader
module. For this the structure / format of our Routes Tree Configuration File should look like this:
Code Snippet 5. Basic structure of the Routes Tree Configuration File
module.exports.conf = function(fieldsLoader){
return {
routes:{
// here go all of the supported routes of the application
}
}
};
You might have noticed the term "Tree" in the name of the "Routes Tree Configuration File". Before further analysing the
way we can define your routes in here, it's good to mention a few things regarding its concept.
In an application there might be routes of the same url (e.g. /a/b) but of different types (e.g. GET, POST). Also, in
an application there might be routes that do something and also subroutes of it that do something else. For example,
there might be the route /a/b and also the route /a/b/c.
The way the routes are defined on the Routes Tree Definition File respect both of the above facts. On any given path you
can separately define the various supported call types and then you can continue deeper defining the supported subroutes of it.
In the specific example here's a possible / valid Routes Tree Configuration File:
Code Snippet 6. Routes Tree Configuration File including paths and endpoints
module.exports.conf = function(fieldsLoader){
return {
routes:{
a:{
subRoutes: {
b: {
get: {
// here goes the GET /a/b route definition
},
post: {
// here goes the POST /a/b route definition
},
subRoutes: {
c: {
get: {
// here goes the GET /a/b/c route definition
}
}
}
}
}
}
}
}
};
In general, the tree that we are defining here consists of paths and endpoints. Everything starts on the "routes" parameter
of the returned object. "a" represents a path, the path "/a". This path has subRoutes, like "/a/b". So, we define these
subroutes on the "subRoutes" parameter of it.
"b" is a path itself as well. Following the object's structure, is obvious that it represents the path "/a/b". A path might
have (or might not have) endpoints. For example the path "/a" does not have any endpoints. Though, path "/a/b" has get and post
endpoints.
The endpoints are defined by the use of the corresponding key (one of "get", "post", "put", "delete"). The endpoints are the "leafs"
of this tree while the paths act as the branches.
A branch can have sub-branches and leafs. A leaf cannot have neither sub-branches nor sub-leafs, and that's we call then "endpoints".
Within the "subRoutes" parameter of any path we can only define paths.
On any endpoint we can define the fields that we're expecting.
Here's a table with all the supported attributes of each element:
Table 4. Path's supported attributes
Attribute name
Description
groups
an array containing all the groups the path belongs to
subRoutes
an object which keys will represent the next sub-section of the path
any of the supported call types (one of "get", "post", "put", "delete")
defines an endpoint to the specific path. E.g. by placing the "get" key on a path it's value must be an object defining
the characteristics of the specific endpoint
Table 5. Endpoints's supported attributes
Attribute name
Description
groups
an array containing all the groups the path belongs to
alias (optional)
a string representation / alias name of the specific endpoint
description (optional)
a human readable description of the endpoint. This will be used on the auto-generated documentation of your API
fields (optional)
an array containing all the fields that are expected on this endpoint. It will be used both by the validator and the
auto-generated documentation process. If your endpoint does not expect any parameters or you don't want to apply any
params validation you can just skip it
mock
in cases you want a specific endpoint to serve mock data just put the mock attribute and set it to true
Groups
Both on tables 4 and 5 you might have noticed the "groups" attribute. The "groups" attribute helps us organize / categorize
all of our endpoints into categories / groups.
The grouping mechanism follows a waterfall inheritance mechanism, just like inheritance works on html elements. Every child inherits
by default the groups of its closest parent. If its closest parent has no group definition then that means it inherits its own
closest parent's groups etc.
For any element in our tree (either endpoint or path), this inheritance goes all the way up until we have an explicit groups definition.
So if you have endpoints / routes defined on /admin/* and all belong to a specially restricted area of your application, where
admin authentication should take place, the only thing you have to do is to define on the /admin path the groups equal to ['admin']. All
of the child paths and endpoints of it will inherit this groups definition.
At any point, at any path or endpoint, you can explicitly define the groups attribute. By this way, any inherited value of the
attribute "groups" will be ignored and the explicitly defined will prevail.
By organizing the endpoints into groups on the Routs Tree Configuration File gives us the opportunity apply middlewares
specially developed for each of these groups. We'll see more details on this later on.
Finally, as you might have noticed, groups is an array. That means that for an endpoint belonging to more than one groups,
all middlewares of all groups it belongs to will be applied in the sequence the group names have been placed within the array.
Alias / Mock operation
The "alias" attribute of each endpoint gives us a way to refer to this endpoint from any other part of the Express Happiness
ecosystem. The most important usage of this "alias" has to do with the mock operation. As mentioned on table 5, along with the
"alias" attribute each endpoint (optionally, default = false) might have a "mock" attribute set to true.
We will analyse mock operation in details in a following part of this document, though keep just one thing in mind for now.
If any of the endpoints has been set to server mock data then a file containing the mock response should be present somewhere in
your hard drive. The folder that contains all mock files is defined on ExpressHappiness invocation, though the actual name
of the file, for each endpoint, should be identical with its alias.
fields
The fields is an array containing all the fields that the specific endpoint supports / expects. As explained, all of the
fields / params have a very specific definition pattern that has been analyzed on the Reusable Params File section.
The fields array might "load" fields from the reusable fields or can either include newly defined params.
In order to load a parameter from the params defined on the Reusable Params File you should use the method "getField" of the
FieldsLoader module that comes with the ExpressHappiness framework.
Here is a complete example, using the fields defined on code snippet 3:
Code Snippet 7. Routes Tree Configuration File example with fields loading
As you can see, on the GET "/a/b" endpoint we have defined three fields:
by loading the "id" field. The resulting field is identical as the definition of the field on the Reusable Params File (code snippet 3)
by loading the "category" field and passing second argument on getField. The "getField" method of FieldsLoader takes a second optional
attribute. This attribute is an object. All own keys of this object that are included in the supported params attrs list (table 2) will overwrite the
ones defined on the Reusable Params File.
A totally new parameter. There are cases where a parameter might appear only once and only in one endpoint. In such cases there's
absolutely no need to define it on the Reusable Params File but, instead, you can define it directly on the "fields" array of the endpoint.
Dynamic routes
A question that arises has to do with the dynamic routes (e.g. "/a/b/:c"). This is of course supported by ExpressHappiness
and you can totally use it on your Routes Tree Configuration File. You can access these fields as you would usually do through
the req object of express.
Here's a simple demonstration on how to define routes including dynamic params:
Code Snippet 8. Dynamic Route Params
module.exports.conf = function(fieldsLoader){ // mind the "fieldsLoader" argument
return {
routes:{
a:{
subRoutes: {
":b": { // check the ":b" on the subRoute key
get: {
// endpoint definition
}
}
}
}
}
}
};
Error Handling and Error Handling Configuration File
The way errors are handled by Express Happiness is centralized and configurable. All errors, including the unknown, are
handled by the framework itself and the developer has the ability to configure the behaviour of the app in each error type.
Express Happiness also provides the ability to define custom error types, define the behaviour of the app in each of them,
trigger such errors from anywhere in your middlewares chain and let the framework take care of them accordingly.
The way each error type should be treated by the application is defined on the Error Handling Configuration File.
The basic structure of this file is the following:
exports.errors = {
undefinedError:{
log:true,
humanReadable: 'Unresolved error code',
sendToClient: {
code:500,
data: 'ErrCode: 1 - There was an error fulfilling your request at the moment. Please try again in a while'
},
hooks:[
// here you can put whatever you want
]
},
'404':{
log:true,
sendToClient: {
code:404,
data:'Invalid route'
}
},
'my_custom_error_code':{
log:false,
sendToClient:{
code:500,
data:'There was an error fulfilling your request'
}
}
}
The Error Handling Configuration File exports an object. Each object key represents the "type" of the error. So, in our
example, if an undefined error gets triggered by the app, our application will log it, it will write to the log file the
text "Unresolved error code" and the client will receive a 500 code along with the body "ErrCode: 1 - There was an error
fulfilling your request at the moment. Please try again in a while".
Let's dive deeper and see which attributes are supported for each error type defined on this file.
Table 6. Supported attributes on error configuration
Attribute name
Type
Mandatory
Description
log
boolean
no (default: false)
If log is set to true, this error will be logged to the error.log file
humanReadable
string
no
a human readable description of the error. This is what it will get logged to the error.log file if log is set to true
sendToClient
object with two keys: code and data
no
with the use of this attribute you can define the response code and the response body that will be sent back to the client. If you
want to send to the client the details of the error object just put there (in quotes) 'err.details'
hooks
array
no
a list of functions to be executed whenever an error of this type occurs. The hook functions should take 3 arguments:
req (the req object)
errorDefinitionObject (the error definition object taken from the Error Handling Configuration File)
err (the actual error triggered during the call stack)
These hook functions get executed before your app responds to the client they are not part of the calls chain (they do not
act as middlewares)
Triggering Errors
Once you define all of your error on the Error Handling Configuration File you can at any time, from anywhere on your code
trigger any of these by the use of this, simple, code:
Code Snippet 10. Triggering errors
var err = new Error();
err.type = 'my_custom_error';
err.details = 'The details of the error. Might be either a string, such as this, or any other data type (object, array etc)';
return next(err);
In order for this part of code to work you must have the "next" function available.
Fot those who are not that familiar with "next" function, please have a look here.
Once you trigger this event the rest is on Express Happiness to take care of, according to the Error Handling Configuration File.
Predefined Errors
Express Happiness comes with a series of error types predefined. These are:
undefinedError It's triggered for errors that don't belong to any of the defined errors. It's default configuration
is:
{
log: true,
humanReadable: 'There is no mock data available for this route yet',
sendToClient: {
code: 404,
data:'There is no mock data available for this route yet'
}
}
underDevelopment It's triggered in cases there's no controller function defined for a specific route.
It's default configuration is:
{
log: false,
humanReadable: 'A call to a route under development has been made',
sendToClient:{
code:501,
data:'This route is currently under development'
}
The default behaviour on any of these errors can be altered by redefining them on the Error Handling Configuration File.
error.log file
As mentioned earlier in this document, Express Happiness logs errors on an error log file. This file is defined on application
start. Express Happiness does not log all the errors but only those which have log:true on their definition on the Error
Handling Configuration File.
What's been logged on this document, for each error, is:
Code Snippet 12. Error Line structure logged on the error log file
date | error code | route | human readable explanation of the error | error details
Mock Operation
For any endpoint that you define on your Routes Tree Configuration File, you have the chance to put it in mock operation
status. By "mock operation status" we mean that whenever a user hits the endpoint a static, predefined, mock response will
be served.
In order to do that you need two things:
Configure the endpoint to serve only mock data
Create a JSON file and put it in you mock files folder
How to set mock operation on
There are multiple ways to do that. First of all, in order to enable mock operations you have to set the mockData operation
on during the initialization of your application. We will see more details regarding the initial configuration object
passed on application start later on, though for now just keep in mind that when we start our application we pass a configuration
object which on "mockData" key holds an object that defines the folder of your mock files and the flag that set mock operation
on or off.
Having our mock folder defined and set mock operation to on we can force an endpoint to serve mock data by:
Putting in our mock files folder a file with the name --endpoint-alias--.json, where "--endpoint-alias--" is the alias
of the endpoint defined on the key "alias" of the endpoint on the Routes Tree Configuration File
Setting the operation status of the endpoint to mock by setting the "mock" attribute of the endpoint on the Routes Tree
Configuration File to true
Or by passing the parameter "mock" equals to 1 during the call
By this way, whenever you hit the specific endpoint you'll always get back the mock data defined on the specified file on
the mock files folder.
Controller Functions
Up to now we've seen almost everything regarding the definition process of an endpoint, the params validation and the error
handling mechanisms but we've said nothing regarding the actual controller function.
Assuming that a call passes all the middlewares, all the checks and it's not on mock operation status it reaches to the point
where something actual needs to take place, a controller function should take care of the call.
All controller functions are defined in a single file. As stated in the beginning of this document, the actual aim of this
architectural decision is not, of course, to pack all the code within this file but more to have one single point where you
can assign responsibilities and define the controllers of all of your routes in a clean and readable way.
This single file is called Controller Functions File and it looks like this:
Code Snippet 12. Example of Controller Functions File
var adminFunctions = require('./functions/admin.js');
var userFunctions = require('./functions/user.js');
var functions = {};
functions['route-alias-1'] = adminFunctions.doSomething;
functions['route-alias-2'] = userFunctions.doSomethingElse;
exports.functions = functions;
It's just a mapping of all controller functions to the routes. As you can see from the example snippet 12, the Controller
Functions File should export an array. An associative array the keys of which are alias name of each route and the values
the corresponding controller functions of them.
The controller function for each endpoint is in the exact same format as a simple controller function that you would define
if you used express without Express Happiness. That is:
Code Snippet 13. Controller Function format
var my_controller_function = function(req, res, next){
// do your magic here
}
The third argument (next) is optional though if you want to use the automatic error handling mechanism within these functions
(that means to create a custom error, trigger it and let the Error Handling mechanism take care of it) you
certainly need the next function (see code snippet 10).
Application Configuration on start
Having the full of your application configured it's now time to fire it up. Express Happiness starts with the command:
Code Snippet 15. Starting your Express Happiness Server
First thing to do is to create a new Express Happiness instance. This is done by calling "new expressHappiness" function.
This function takes three parameters:
app: the application initialized by the express() function invocation
router: The Router object provided by express which we can get through express.Router() invocation
configuration: a configuration object that sets the full Express Happiness environment up. Here we define the
path of each file needed by EH and also the mock operation configuration.
After creating the EH instance we call the "generate" function of it. The "generate" function takes three parameters:
route path: this is the base url that our application will support. For example if we are developing a REST
API that listens to paths under /v1/ then we don't need to define this on the Routes Tree Configuration File. We can
define it here by passing the '/v1' value on the first argument of the generate function
pre-validation middlewares: On the middlewares chain that are been executed on each call on our application,
EH always includes a middleware that performs the params validation for the given endpoint. The second argument
of the "generate" function provides us the ability to define a series of middlewares we want to get executed before reaching
the params validation step. The middlewares defined here, most often have to do with authentication issues.
The way we define our middlewares provides us the ability to explicitly define which middlewares should be executed according
the group that each route belongs to (see table 5). As mentioned, each endpoint might belong to one or more groups and this
is defined by the "groups" attribute (which holds an array). So, in our example for all endpoints that belong to the 'userAccess' group
the middlewareA and middlewareB functions will be executed before the middlewares chain reaches the params validation step. For
all middlewares that belong to the 'adminAccess' group the middlewareC and middlewareD will be executed before the params
validation middleware gets execute and so on.
If we want to define pre-validation middlewares for all of our endpoints, no matter the groups they belong to, we can use
the "eh-allRoutes" key to define them. All middlewares included on this array are going to be executed, in the order they
appear within the array, on all of our endpoints.
post-validation middlewares: The exact same things stand here. The third argument of the "generate" function
expects an object that though its keys defines the middlewares to be executed after the params validation process, on
our routes, depending on the groups they belong to.
The form of our middlewares should be the typical middleware form of express: function(req, res, next).
Auto-generated API documentation
After defining all of your endpoints with types and parameters on the root of your application there will be the documentation
of your API. So, for example, if you run your app on localhost, port 7000, on http://localhost:7000 you'll find an
auto-generated REST API documentation page.
================================================
FILE: RESTcallsValidator.js
================================================
var erH, reusableRequiredFields;
var validator = require('validator');
var moment = require('moment');
var restConf = {};
exports.assignConf = function(conf){
restConf = conf;
}
exports.init = function(confObj){
errorHandler = require('./ErrorHandler.js');
erH = new errorHandler(confObj.errorFile, confObj.errorsConfigurationFile);
reusableRequiredFields = require(confObj.reusableFieldsFile);
}
var validateEmail = function(email){
var re = /^[a-zA-Z0-9+._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6}$/;
return re.test(email);
}
var hasTheErrorKey = function(field, errorKey){
if(field.validationFailureTexts != null && field.validationFailureTexts != undefined){
if(field.validationFailureTexts[errorKey] != null && field.validationFailureTexts[errorKey] != undefined){
return field.validationFailureTexts[errorKey]
}
}
return false;
}
var unitValidator = {
int: function(field, value, path, errors, callback){
var fieldNameOnResponse = field.humanReadable || path.join('.');
if(!validator.isInt(value)){
var er_message = hasTheErrorKey(field, 'type');
if(er_message === false){
errors.push(fieldNameOnResponse + ' must be an integer. ' + value + ' provided.');
} else {
errors.push(er_message);
}
} else {
if(!!field.min){
if(value < field.min){
var er_message = hasTheErrorKey(field, 'min');
if(er_message === false){
errors.push(fieldNameOnResponse + ' must be greater or equal to ' + field.min + '. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
}
if(!!field.max){
if(value > field.min){
var er_message = hasTheErrorKey(field, 'max');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be lower or equal to ' + field.max + '. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
}
}
callback();
},
date: function(field, value, path, errors, callback){
var fieldNameOnResponse = field.humanReadable || path.join('.');
var momentObj = moment(value, field.validationString);
if(!momentObj.isValid()){
var er_message = hasTheErrorKey(field, 'validationString');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be a date in the format: ' + field.validationString + '. ' + value + ' provided.');
} else {
errors.push(er_message);
}
} else {
// in case of dates, for easiness we keep the momentObj representation of the passed variable, no matter
// which is the format of the date that we expect
//req.filteredParams[path.join('.') + field.key].momentObj = momentObj;
}
callback();
},
oneof: function(field, value, path, errors, callback){
var fieldNameOnResponse = field.humanReadable || path.join('.');
if(field.acceptedValues.indexOf(value) == -1){
var er_message = hasTheErrorKey(field, 'acceptedValues');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be one of ' + field.acceptedValues.join(', ') + '. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
callback();
},
boolean: function(field, value, path, errors, callback){
var fieldNameOnResponse = field.humanReadable || path.join('.');
if(value !== true && value !== false && value !== 'true' && value !== 'false'){
var er_message = hasTheErrorKey(field, 'type');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be a boolean. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
callback();
},
numeric: function(field, value, path, errors, callback){
var fieldNameOnResponse = field.humanReadable || path.join('.');
if(!validator.isFloat(value)){
var er_message = hasTheErrorKey(field, 'type');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be a number. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
callback();
},
email: function(field, value, path, errors, callback){
var fieldNameOnResponse = field.humanReadable || path.join('.');
if(!validateEmail(value)){
var er_message = hasTheErrorKey(field, 'type');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be a valid email address. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
callback();
},
string: function(field, value, path, errors, callback){
var fieldNameOnResponse = field.humanReadable || path.join('.');
if(!!field.minChars){
if(value.length < field.minChars){
var er_message = hasTheErrorKey(field, 'minChars');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be of at least ' + field.minChars + ' long. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
}
if(!!field.maxChars){
if(value.length > field.maxChars){
var er_message = hasTheErrorKey(field, 'maxChars');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be of at max ' + field.maxChars + ' long. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
}
if(!!field.regexp){
var er_message = hasTheErrorKey(field, 'type');
try{
var passes = field.regexp.test(value);
if(!passes){
if(er_message === false) {
errors.push(fieldNameOnResponse + ' do not match the provided regular expression');
} else {
errors.push(er_message);
}
}
} catch(err){
if(er_message === false) {
errors.push(fieldNameOnResponse + ' do not match the provided regular expression');
} else {
errors.push(er_message);
}
}
}
callback();
},
array: function(field, value, path, errors){
var fieldNameOnResponse = field.humanReadable || path.join('.');
if(!(variable.constructor === Array)){
var er_message = hasTheErrorKey(field, 'type');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be of type array. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
if(!!field.minLength){
if(value.length < field.minLength){
var er_message = hasTheErrorKey(field, 'minLength');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be of at least of ' + field.minLength + ' length. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
}
if(!!field.maxLength){
if(value.length > field.maxLength){
var er_message = hasTheErrorKey(field, 'maxLength');
if(er_message === false) {
errors.push(fieldNameOnResponse + ' must be of max length ' + field.maxLength + '. ' + value + ' provided.');
} else {
errors.push(er_message);
}
}
}
callback();
}
};
var firstLevelIterator = function(fields, errors, req, func, callback){
var index = 0;
var done = false;
var iterations = fields.length;
var loop = {
next: function(){
if(done){
return;
}
if(index < iterations){
var self = this;
var theField = fields[index];
unitValidate(theField, errors, req, [theField.key],
function(){
index++;
func(self);
}
);
} else {
done = true;
callback();
}
}
}
loop.next();
return loop;
}
var validate = function(obj, errors, req, path, func, callback) {
var index = 0;
var done = false;
var iterations = Object.keys(obj.keys).length;
var objKeys = Object.keys(obj.keys);
var loop = {
next: function() {
if (done) {
return;
}
if (index < iterations) {
var newPath = path.slice();
newPath.push(objKeys[index]);
var self = this;
unitValidate(obj.keys[objKeys[index]], errors, req, newPath, function(){
index++;
func(self);
});
} else {
done = true;
callback();
}
}
};
loop.next();
return loop;
};
/*
@unit: the unit to be validated taken from the signature
@req: the request object
@path: the base path of the current unit. It's an array
@isRoot: a boolean indicating whether the passed unit is the root definition object or not
@unitValidator: an instance of the unitValidator object defined above
@callback: the callback to be called after the validation process
*/
var unitValidate = function(unit, errors, req, path, callback){
var get = req.expressHappiness.get;
var set = req.expressHappiness.set;
// step 1: check if the parameter is present if it's mandatory according to the signature
var mandatoryIssue = false;
if(path.length > 0){
if(unit.mandatory){
try{
var test_var = get(path[0]);
for(var i=1; i 0) {
var err = new Error();
err.type = 'invalidAttrs';
err.details = errors;
return next(err);
} else {
return next();
}
});
}
}
var turnToFiltered = function(params){
var filtered = {};
for(k in params){
filtered[k] = {
value: params[k]
};
}
return filtered;
}
================================================
FILE: conf/conf.js
================================================
var path = require('path');
exports.conf = {
errorLogFile: path.resolve(__dirname, '../') + '/logs/error.log',
mockOperations:{
"get:/kpis/traffic":false,
"get:/kpis/traffic/powerHours": false,
"get:/kpis/traffic/entrances":false,
"get:/kpis/dwellTime":false,
"get:/kpis/loyalty":false,
"get:/kpis/grossShoppingHours":false,
"get:/kpis/shoppersVsTravellers":true,
"get:/kpis/mallUse":true,
"get:/kpis/areaUse":true,
"get:/kpis/visitFrequency":true,
"get:/kpis/abandonmentRate":false,
"get:/kpis/drawRate":false,
"get:/kpis/opportunity":false,
"get:/kpis/hierarchy": true,
"get:/sites/:site_id/locations": false
},
jwtSecret: 'N##$%W$&SFGHY$$^#W#%YLK"HBH4l5hjhbkdsljly5%$elawkjgy3%Y4foijfAWT$QTJQALDGKSDJFY$%L^KJ%^'
};
================================================
FILE: conf/errors.js
================================================
exports.errors = {
undefinedError:{
log:false,
humanReadable: 'Unresolved error code',
sendToClient: {
code:200,
data: 'ErrCode: 1 - There was an error fulfilling your request at the moment. Please try again in a while'
},
hooks:[
// here you can put whatever you want
]
}
}
================================================
FILE: conf/restConf.js
================================================
/*
All routes might belong to none, one or more groups.
Grouping routes helps us apply middlewares targeting only specific sets of routes
Grouping routes follows waterfall inheritance model. A group assigned to a route is been inherited by default by
all of its subroutes. For example:
routes:{
routeA:{
groups:['groupA'],
subRoutes:{
routeB:{
// routeB by default belongs to 'groupA'
}
}
}
}
we can always change the groups that groupB (or any other sub-route) belongs to by redefining the groups attribute
for example if want routeB not to belong on groupA but to belong on groupB then we can do it by:
routes:{
routeA:{
groups:['groupA'],
subRoutes:{
routeB:{
groups:['groupB']
}
}
}
}
and if want groupB to belong on groups at all then an empty groups attribute would do it:
routes:{
routeA:{
groups:[],
subRoutes:{
routeB:{
// routeB by default belongs to 'groupA'
}
}
}
}
*/
module.exports.conf = function(fieldsLoader){
return {
// API routes signatures
routes:{
kpis:{
groups:['userAccess'],
subRoutes:{
traffic:
{
get:{
description:'Get the traffic',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('siteId'),
fieldsLoader.getField('locationId'),
fieldsLoader.getField('reportStartDate'),
fieldsLoader.getField('reportEndDate'),
fieldsLoader.getField('compareStartDate'),
fieldsLoader.getField('compareEndDate'),
fieldsLoader.getField('groupBy'),
fieldsLoader.getField('countType'),
fieldsLoader.getField('includeUnique'),
fieldsLoader.getField('includeReturning')
]
},
subRoutes:{
powerHours: {
get:{
description:'Get the traffic power hours',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('siteId'),
fieldsLoader.getField('reportStartDate'),
fieldsLoader.getField('reportEndDate'),
fieldsLoader.getField('countType'),
fieldsLoader.getField('basePercentage')
]
}
}
,entrances:{
get:{
description:'Get the traffic monitoring point / quarter hour data',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('siteId'),
fieldsLoader.getField('reportStartDate'),
fieldsLoader.getField('reportEndDate'),
fieldsLoader.getField('countType'),
fieldsLoader.getField('groupBy', {mandatory:true})
]
}
}
}
}
,
dwellTime:{
get:{
description:'Get dwell time',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('siteId'),
fieldsLoader.getField('locationId'),
fieldsLoader.getField('reportStartDate'),
fieldsLoader.getField('reportEndDate'),
fieldsLoader.getField('compareStartDate'),
fieldsLoader.getField('compareEndDate'),
fieldsLoader.getField('groupBy'),
fieldsLoader.getField('includeDist'),
{
key:'allLocations',
type:'boolean',
humanReadable: 'get massive report for all locations',
description:'Get data for all locations of a given site but for each location separately',
mandatory:false,
default:false
}
]
}
},
loyalty:{
get:{
description:'Get loyalty',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('siteId'),
fieldsLoader.getField('locationId'),
fieldsLoader.getField('reportStartDate'),
fieldsLoader.getField('reportEndDate'),
fieldsLoader.getField('compareStartDate', {mandatory:true}),
fieldsLoader.getField('compareEndDate', {mandatory:true}),
fieldsLoader.getField('type')
]
}
},
grossShoppingHours:{
get:{
description:'Get gross shopping hours',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('siteId'),
fieldsLoader.getField('locationId'),
fieldsLoader.getField('reportStartDate'),
fieldsLoader.getField('reportEndDate'),
fieldsLoader.getField('compareStartDate'),
fieldsLoader.getField('compareEndDate'),
fieldsLoader.getField('groupBy'),
fieldsLoader.getField('includeUnique'),
fieldsLoader.getField('includeReturning')
]
}
},
shoppersVsTravellers:{
get:{
description:'Get shoppers vs travellers',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('reportStartDate'),
fieldsLoader.getField('reportEndDate'),
fieldsLoader.getField('compareStartDate'),
fieldsLoader.getField('compareEndDate'),
fieldsLoader.getField('groupBy')
]
}
},
abandonmentRate:{
get:{
description:'Get abandonment rates',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('siteId'),
fieldsLoader.getField('locationId'),
fieldsLoader.getField('reportStartDate'),
fieldsLoader.getField('reportEndDate'),
fieldsLoader.getField('compareStartDate'),
fieldsLoader.getField('compareEndDate'),
fieldsLoader.getField('groupBy')
]
}
},
drawRate:{
get:{
description:'Get draw rate',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('siteId'),
fieldsLoader.getField('locationId'),
fieldsLoader.getField('reportStartDate'),
fieldsLoader.getField('reportEndDate'),
fieldsLoader.getField('compareStartDate'),
fieldsLoader.getField('compareEndDate'),
fieldsLoader.getField('groupBy')
]
}
},
opportunity:{
get:{
description:'Get opportunity',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('siteId'),
fieldsLoader.getField('locationId'),
fieldsLoader.getField('reportStartDate'),
fieldsLoader.getField('reportEndDate'),
fieldsLoader.getField('compareStartDate'),
fieldsLoader.getField('compareEndDate'),
fieldsLoader.getField('groupBy')
]
}
}
}
},
auth: {
post: {
description:'Authenticate user',
fields:[
fieldsLoader.getField('username'),
fieldsLoader.getField('user_password')
]
}
},
users:{
groups:['superUserAccess'],
get:{
description:'Get users',
fields:[]
},
post:{
description:'Post new user',
fields:[
fieldsLoader.getField('username'),
fieldsLoader.getField('user_password')
]
},
subRoutes:{
':user_id':{
get:{
description:'Get a specific user info',
fields:[]
},
put:{
description: 'Edit user\'s info',
fields:[
fieldsLoader.getField('user_password', {mandatory: false}),
fieldsLoader.getField('expired'),
fieldsLoader.getField('accessMap')
]
},
delete:{
description: 'Delete user',
fields:[]
}
}
}
},
organizations:{
groups:['userAccess'],
get:{
groups:[], // the endpoint will check access to filter down org list
description:'Get organizations list',
fields:[]
},
post:{
groups:['superUserAccess'],
description:'Create a new organization',
fields:[
fieldsLoader.getField('orgId'),
fieldsLoader.getField('name')
]
},
subRoutes:{
':orgId':{
get:{
description: 'Organization\'s details',
fields:[]
},
put:{
description:'Edit organization\'s data',
fields:[
fieldsLoader.getField('name'),
fieldsLoader.getField('expired')
]
},
delete:{
description: 'Delete organization',
fields:[]
},
subRoutes:{
users:{
groups:['orgAdmin'],
get:{
description:'Get all users for which current user is an org admin',
fields:[]
},
post:{
description:'Add user to the current organization. Create user if it does not exist.',
fields:[
fieldsLoader.getField('username'),
fieldsLoader.getField('user_password', {mandatory: false})
]
},
subRoutes:{
':user_id':{
get:{
description:'get the user data, including access map. if user does not exist OR is not in org, return not found',
fields:[]
},
put:{
description:'update user data, including access map. if user does not exist OR is not in org, return not found',
fields:[
fieldsLoader.getField('user_password', {mandatory: false}),
fieldsLoader.getField('expired'),
fieldsLoader.getField('accessMap')
]
},
delete:{
description:'remove user from organization. Never removes the user completely',
fields:[]
}
}
}
},
sites:{
get:{
description:'Get sites list',
fields:[]
},
post:{
description:'Create a new site',
fields:[
fieldsLoader.getField('siteId'),
fieldsLoader.getField('name', {
description:'Site name',
humanReadable: 'Site name'
}),
fieldsLoader.getField('name', {
key:'organization_name'
}),
fieldsLoader.getField('geo')
]
},
subRoutes:{
':siteId':{
get:{
description: 'Site\'s details',
fields:[]
},
put:{
description:'Edit site\'s data',
fields:[
fieldsLoader.getField('name', {
description:'Site name',
humanReadable: 'Site name'
}),
fieldsLoader.getField('name', {
key:'organization_name'
}),
fieldsLoader.getField('geo'),
fieldsLoader.getField('expired')
]
},
delete:{
description: 'Delete site',
fields:[]
},
subRoutes:{
locations:{
get:{
description: 'Get site\'s locations',
fields:[]
},
post:{
description:'Create a new location',
fields:[
fieldsLoader.getField('location_id'),
fieldsLoader.getField('location_type'),
fieldsLoader.getField('name', {
key:'site_name',
description:'Site name',
humanReadable: 'Site name'
}),
fieldsLoader.getField('name', {
key:'organization_name',
description:'Organization name',
humanReadable: 'Organization name'
}),
fieldsLoader.getField('description'),
fieldsLoader.getField('beacon_id'),
fieldsLoader.getField('generic_other', {
key:'nested_set_left'
}),
fieldsLoader.getField('generic_other', {
key:'nested_set_right'
}),
fieldsLoader.getField('generic_other', {
key:'nested_set_depth'
}),
fieldsLoader.getField('traffic_monitoring_point_entrance_id'),
fieldsLoader.getField('traffic_monitoring_point_description')
]
},
subRoutes:{
':locationId':{
get:{
description: 'locations\'s details',
fields:[]
},
put:{
description:'Edit locations\'s data',
fields:[
fieldsLoader.getField('location_type'),
fieldsLoader.getField('name', {
key:'site_name',
description:'Site name',
humanReadable: 'Site name'
}),
fieldsLoader.getField('name', {
key:'organization_name',
description:'Organization name',
humanReadable: 'Organization name'
}),
fieldsLoader.getField('description'),
fieldsLoader.getField('beacon_id'),
fieldsLoader.getField('generic_other', {
key:'nested_set_left'
}),
fieldsLoader.getField('generic_other', {
key:'nested_set_right'
}),
fieldsLoader.getField('generic_other', {
key:'nested_set_depth'
}),
fieldsLoader.getField('traffic_monitoring_point_entrance_id'),
fieldsLoader.getField('traffic_monitoring_point_description'),
fieldsLoader.getField('expired')
]
},
delete:{
description: 'Delete locations',
fields:[]
}
}
}
}
}
}
}
}
}
}
}
}
}
}
};
================================================
FILE: expressHappiness.js
================================================
var restConf = {
routes:[]
}
var kpis
,rcv;
var fs = require('fs');
var colors = require('colors');
var flatSignature = [];
var app, router, confObj;
var eh = function(p_app, p_router, conf){
app = p_app;
router = p_router;
var path = require('path');
var appDir = path.dirname(require.main.filename);
this.generate = successGenerate;
confObj = {
mockData:{
enable: true,
folder: appDir + '/mockJSONs',
global:false
},
reusableFieldsFile: appDir + '/expressHappiness/reusableFields.js',
errorFile:appDir + '/expressHappiness/errors.log',
errorsConfigurationFile:appDir + '/expressHappiness/conf/errors.js',
apiConfigurationFile:appDir + '/expressHappiness/conf/restConf.js',
controllersFile:appDir + '/expressHappiness/controllerFunctions.js'
};
if(!conf){
conf = {};
}
for(var propertyName in conf) {
if(conf.hasOwnProperty(propertyName)){
confObj[propertyName] = conf[propertyName];
}
}
var errorOccurred = false;
if(!fs.existsSync(confObj.reusableFieldsFile)){
errorOccurred = true;
var msg = "Reusable fields file (" + confObj.reusableFieldsFile + ") does not exist. Please create it according the documentation";
console.log(msg.red.bgWhite);
}
if(!fs.existsSync(confObj.errorFile)){
errorOccurred = true;
var msg = "Error log file (" + confObj.errorFile + ") does not exist. Please create it according the documentation";
console.log(msg.red.bgWhite);
}
if(!fs.existsSync(confObj.errorsConfigurationFile)){
errorOccurred = true;
var msg = "Errors configuration file (" + confObj.errorsConfigurationFile + ") does not exist. Please create it according the documentation"
console.log(msg.red.bgWhite);
}
if(!fs.existsSync(confObj.apiConfigurationFile)){
errorOccurred = true;
var msg = "REST API configuration file (" + confObj.apiConfigurationFile + ") does not exist. Please create it according the documentation"
console.log(msg.red.bgWhite);
}
if(!fs.existsSync(confObj.controllersFile)){
errorOccurred = true;
var msg = "Controller functions definition file (" + confObj.controllersFile + ") does not exist. Please create it according the documentation"
console.log(msg.red.bgWhite);
}
if(confObj.mockData.enable && !fs.existsSync(confObj.mockData.folder)){
errorOccurred = true;
var msg = "Mock data folder (" + confObj.mockData.folder + ") does not exist. Please create it according the documentation"
console.log(msg.red.bgWhite);
}
if(errorOccurred){
this.generate = failureGenerate;
} else {
// Rest validation initialization
var FL = require('./fieldsLoader.js');
var fieldsLoader = new FL(confObj.reusableFieldsFile);
restConf = require(confObj.apiConfigurationFile).conf(fieldsLoader);
global.expressHappiness = {
confObj: confObj
};
// TODO change the folder
rcv = require('./RESTcallsValidator.js');
rcv.init(confObj);
rcv.assignConf(restConf);
kpis = require(confObj.controllersFile);
}
this.start = function(port){
if(!port){
var msg = "Please enter the port number for the app to run. Exiting.";
console.log(msg.red.bgWhite);
process.exit(1);
} else {
isPortTaken(port, function(err, taken){
if(taken) {
var msg = 'Port ' + port + ' is been used by another application. Exiting.';
console.log(msg.red.bgWhite);
process.exit(1);
} else {
p_app.listen(port);
var msg = 'The application is listening on port ' + port + ' for connections.';
console.log(msg.green);
}
});
}
}
}
/*
checks if the port is taken
*/
var isPortTaken = function(port, fn) {
var net = require('net')
var tester = net.createServer()
.once('error', function (err) {
if (err.code != 'EADDRINUSE') return fn(err)
fn(null, true)
})
.once('listening', function() {
tester.once('close', function() { fn(null, false) })
.close()
})
.listen(port)
}
/* Reads the restConf and generates all available routes according to it.
Also, it acts as debugger. For each of the generated routes the generate function checks if there is
a corresponding method defined on the kpi controller, if there is mock data file available and it logs everything
to the console.
Missing methods are replaced by a generic one which handles their absence.
Also, routes that do not provide mock data are configured so noMockAvailable function will be called whenever
mock operation is on for them. For routes that actually have corresponding mock data files available the
makeMockQuery function will be invoked for mock operation cases. Also, for efficiency reasons the makeMockQuery function
for each of the routes that actually provide mock data is been generated once here (by reading the corresponding file)
and it's been passed, so only one file read occurs for each route, only once, only at the kick off.
It takes three parameters:
@ router [object]: express framework router object
@ baseUrl [string]: the base url of the routes to create
@ preValidationMiddlewares [array][array]: holds all the middlewares that should be applied to the specific routes. These middlewares are been applied before validation
it is an associative array. On restConf.js file each route might belong to one or more groups. For each group there might be different middlewares applied.
This is achieved by using the group names as the first level keys of the array. Each key will hold another array which actual holds
all the middlewares to be applied to the specific groups. Example:
preValidationMiddlewares ~=
[
'userAccess':[middlewareName1, middleware2],
'adminAccess':[middlewareName3, middleware4]
]
if we want to apply a middleware to all of the routes, no matter what then we can define this by including it on the key "eh-allRoutes".
Example:
preValidationMiddlewares ~=
[
'groupNameOne':[middlewareName1, middleware2],
'groupNameTwo':[middlewareName3, middleware4],
'eh-allRoutes':[middlewareToBeAppliedToAllRoutes1, middlewareToBeAppliedToAllRoutes2]
]
@ postValidationMiddlewares [array][array]: holds all the middlewares that should be applied after the validation process and before the controller function invocation
it is an associative array. On restConf.js file each route might belong to one or more groups. For each group there might be different middlewares applied.
This is achieved by using the group names as the first level keys of the array. Each key will hold another array which actual holds
all the middlewares to be applied to the specific groups. Example:
postValidationMiddlewares ~=
[
'groupNameOne':[middlewareName1, middleware2],
'groupNameTwo':[middlewareName3, middleware4]
]
if we want to apply a middleware to all of the routes, no matter what then we can define this by including it on the key "eh-allRoutes".
Example:
postValidationMiddlewares ~=
[
'groupNameOne':[middlewareName1, middleware2],
'groupNameTwo':[middlewareName3, middleware4],
'eh-allRoutes':[middlewareToBeAppliedToAllRoutes1, middlewareToBeAppliedToAllRoutes2]
]
*/
var successGenerate = function(baseUrl, preValidationMiddlewares, postValidationMiddlewares){
var theRoute = router.route(baseUrl + '/');
theRoute.get(putMethodsOnReq('get'));
theRoute.get(putApipathToReq([], ''));
theRoute.get(function(req, res, next){
req.isRoot = true;
return next();
});
for(var i=0; i",
"license": "BSD-2-Clause",
"bugs": {
"url": "https://github.com/andreas-trad/express-happiness/issues"
}
}
================================================
FILE: views/index.html
================================================
KPIS documentation