IMFV

Objective

SOAJS is equipped with an input mapping, filtering and validating mechanism that removes up to 50% of an API code in terms of fetching and cleaning the inputs from POST, GET, SESSION, COOKIES, HEADERS and TENANT CONFIG.

Every service uses the IMFV (input mapping, filtering and validating) to validate the inputs (parameters) of its APIs. IMFV is usually located in a config.js file within the service directory.

This space will show you:

Where the IMFV is defined
Error codes
Sample Schema
Sources List
Default Values
Types, Properties, and Formats
Type Casting
Complex Schemas
Common Fields
API Label Info
Usage
Full Sample

Config.js

The content of this file is based on two main sections: Error Codes ("errors" object) and Validation Schema ("schema" object).

//inside config.js
module.exports={
    "serviceName": "helloworld",
    "servicePort": 4020,
    "extKeyRequired": false,
    "errors": {},
    "schema": {}
}

Error Codes

Error Codes is a list that contains all the errors that might be returned by the service APIs. Each Error consists of a number referred to by code and an error message.

"errors":{
    //...
    401: "unable to login, user not found!",
    402: "Invalid username provided!"
    //...
}

When an error in the service occurs, the service will return back to the user a code and a message for clarification. To use the error codes inside the service code index.js, use req.soajs.buildResponse and provide the error object as the first parameter. The error object is constructed from the code and the message.

//inside index.js
var config = require("./config");
var service = new soajs.server.service(...);
service.post("/login", function(req, res) {
    //...
    if(req.soajs.inputmaskData.username === ''){
        return res.jsonp(req.soajs.buildResponse({"code": 402, "msg": config.errors[402]}));
    }
    //...
};

SOAJS built-in req.soajs.buildResponse takes 2 parameters, the first being an error object and the second being the response.

Sample Schema

Every API has an entry inside the schema object; this is where you configure the inputs that it should receive and their validation.

Every entry instructs IMFV where to look for the input using the source attribute and how to validate the input using the validation attribute.

var config = {
    "serviceName": "helloworld",
    "servicePort": 4020,
    "extKeyRequired": false,
    "schema": {
        //api route
        "/hello": {
            "_apiInfo":{
                "l": "Hello Api"
            },
            'firstName': {
                'source': ['query.firstName'],
                'required': true,
                'validation': {
                    'type': 'string',
                    'format': 'alphanumeric'
                    //...
                }
            }
            //...
        }
        //...
    }
};

The above sample Tells IMFV that for API "/hello" there is a required input called "firstName". It's type is string and it has a specific alphanumeric format and it is provided via the query string as "firstName" when the request is made.

Sources List

IMFV can fetch an input from different sources if configured to do so. In the case above, the "source" array has only one entry which is "query.firstName". However, you can configure IMFV to look in multiple sources for the input. If the first source doesn't contain the input value, IMFV will jump to the next one and so on till the entire "source" array has been processed.

"firstName" : {
        "source": ["query.firstName", "body.firstName", "session.firstName", ...]
}

_{IMFV will look for "firstName" in the following sources, in this order: query string, then posted body, then session...}