A basic SOAJS service is made up of two files:
- config.js: Contains the metadata of the service (name, port, etc...), in addition to that of each of the APIs alongside its corresponding parameters.
- index.js: Contains the implementation of the APIs.
When a request arrives at the service, the IMFV maps, validates, and formats all arriving input parameter, before consolidating them all into one object.
After the IMFV checks for the validity of the supplied input parameters, ensures the existence of all the required parameters, the request is forwarded to the API.
You can learn more on the functionality of the IMFV by visiting the IMFV section.
The below snippets represent the content of both index.js and config.js that represent the Basic SOAJS service (example 01).
Below each snippet is a small explanation of how each of them works.
'use strict';
module.exports = {
serviceName: "example01", //service name
servicePort: 4010, //service port
extKeyRequired: false, //set to true if the service is multi-tenant
"errors": { //object that contains the error codes of the service
"900": "firstName not found"
},
"schema": { //object that contains the APIs schema
"/testGet": { //one API
"_apiInfo":{ //API labels
"l": "Test Get"
},
"firstName": { //API Input
"source": ['query.firstName'],
"required": true,
"validation": {
"type": "string"
}
},
"lastName": { //API Input
"source": ['query.lastName'],
"required": true,
"validation": {
"type": "string"
}
},
"email": { //API Input
"source": ['query.email'],
"required": false,
"validation": {
"type": "string",
"format": "email"
}
}
},
"/testDel": {
"_apiInfo":{
"l": "Test Delete"
},
"firstName": {
"source": ['query.firstName'],
"required": false,
"validation": {
"type": "string"
}
},
"lastName": {
"source": ['query.lastName'],
"required": false,
"validation": {
"type": "string"
}
}
},
"/buildName": {
"_apiInfo":{
"l": "Build Name"
},
"firstName": {
"source": ['query.firstName'],
"required": true,
"default": "John",
"validation": {
"type": "string"
}
},
"lastName": {
"source": ['query.lastName'],
"required": true,
"validation": {
"type": "string"
}
}
},
"/testPost": {
"_apiInfo":{
"l": "Test Post"
},
"firstName": {
"source": ['body.firstName'],
"required": true,
"validation": {
"type": "string"
}
},
"lastName": {
"source": ['body.lastName'],
"required": true,
"validation": {
"type": "string"
}
},
"email": {
"source": ['body.email'],
"required": false,
"validation": {
"type": "string",
"format": "email"
}
}
},
"/testPut": {
"_apiInfo":{
"l": "Test Put"
},
"firstName": {
"source": ['body.firstName'],
"required": true,
"validation": {
"type": "string"
}
},
"lastName": {
"source": ['body.lastName'],
"required": true,
"validation": {
"type": "string"
}
},
"email": {
"source": ['body.email'],
"required": false,
"validation": {
"type": "string",
"format": "email"
}
}
}
}
};
As we mentioned above, the "config.js" contains all the metadata of the service, including its APIs.
In the sample above, there exists information about the service: its name, the port it listens to, the errors, and finally a schema containing the APIs.
Let us analyze the "testGet" API:
Each API is referenced by a label, which is, in this case, "Test Get", under the "_apiInfo" JSON object.
This API expects three input parameters (firstName, lastName, and email) of type String.
These parameters are supplied through the query (i.e. the URL passed in the browser).
More information related to the IMFV can be found under the IMFV section in the documentation.
In this example, the firstName, and lastName are required, whereas the email is not.
Similar to the explained API, the user must add in the schema all the needed APIs, along with any additional information needed.
'use strict';
var soajs = require('soajs'); //require soajs
var config = require('./config.js');
var service = new soajs.server.service(config); //create new service instance
service.init(function () { //initialize the service
service.get("/testGet", function (req, res) { //implement the API business logic
res.json(req.soajs.buildResponse(null, { //generate API response
firstName: req.soajs.inputmaskData.firstName,
lastName: req.soajs.inputmaskData.lastName,
email: req.soajs.inputmaskData.email
}));
});
service.get("/buildName", function (req, res) {
//write your business logic here
var fullName = req.soajs.inputmaskData.firstName + ' ' + req.soajs.inputmaskData.lastName;
res.json(req.soajs.buildResponse(null, {
fullName: fullName
}));
});
service.delete("/testDel", function (req, res) {
// some business logic
res.json(req.soajs.buildResponse(null, true));
});
service.post("/testPost", function (req, res) {
if (req.soajs.inputmaskData.firstName !== 'John') {
//EXAMPLE: to simulate error response return
res.json(req.soajs.buildResponse({"code": 900, "msg": config.errors[900]}));
} else {
res.json(req.soajs.buildResponse(null, {
firstName: req.soajs.inputmaskData.firstName,
lastName: req.soajs.inputmaskData.lastName,
email: req.soajs.inputmaskData.email
}));
}
});
service.put("/testPut", function (req, res) {
res.json(req.soajs.buildResponse(null, {
firstName: req.soajs.inputmaskData.firstName,
lastName: req.soajs.inputmaskData.lastName
}));
});
service.start(); //start the service
});
The sample above contains the implementation of each of the five APIs that form the service.
Consider the first API "testGet", which uses the GET method.
The API generates a JSON response containing the firstName, lastName, and email, obtained from the request.
Another example to consider is the "testPost" API, which uses the POST method.
The API evaluates the firstName parameter. If not equal to "John", it replies with error code 900, which is also defined in the config.js file.
However, if the firstName is equal to "John", the API generates a JSON response containing the firstName, lastName, and email, obtained from the request.
0 Comments