Introduction

The following is a simple example service built using SOAJS, containing a number of APIs, each of which uses a different method: GET, POST, PUT, and DEL.

The example focuses on how easy it is to create a micro-service and its APIs as well as how to use the IMFV.

The Input mapping, filtering and validation (IMFV) is an engine provided by the SOAJS framework and is responsible to fetch and clean the inputs arriving to your API at runtime.

It is based on json-schema and requires minimal configuration. The beauty about this engine is that it eliminates the headache and effort that developers need to fetch and clean inputs from arriving http requests so they can pass it later on to their business logic.

Configure the IMFV as shown in the config.js and you are done. The IMFV will look for the inputs, clean them and consolidate them in one Javascript object called inputmaskData and hand them over to you to use in your API business logic.

Again, a micro-service is a NodeJS server that listens on a certain port and provides of a list of APIs that are atomic.

The "Example01" is a simple micro-service created using SOAJS, it has no security configuration making it accessible by any user.

To create a service, we need to create two files:

index.js: contains the implementation of the API(s).
config.js: contains the configuration of the service

Example01 can be found inside the soajs.examples/example01/.

Code Walkthrough

This page shows you how to interact with example01 service after you install it and run it.

The code walkthrough is located in a sub page and explained in depth. You can click on this link to learn more about how the code works.

Start The Service

Running the service

# go to examples/example01 and start the service
cd soajs.examples/example01/
 
# start the soajs example environment
sudo soajs services start --env=example
 
# export necessary environment variables to create local awareness
export SOAJS_ENV=EXAMPLE
export SOAJS_SRVPORT=4021
export SOAJS_DEPLOY_MANUAL=1
export SOAJS_REGISTRY_API=127.0.0.1:21000
 
 
# start service
node .

Each running service listens on two ports: The data port and the maintenance port.

The service in this example runs on the local machine, and listens on port 4021.

The second port is the maintenance port. The convention we use at SOAJS for maintenance ports is maintenance port = data port + 1000 therefore, the maintenance port is 5010 for this service.

Before starting to experiment with the service's API's, let's run a diagnostic called heartbeat.

A heartbeat is a request that checks the health of the service, and can be performed in the following way:

Heartbeat

curl -X GET "http://127.0.0.1:5021/heartbeat"

The response below indicates that the service is running without any errors.

Response

{"result":true,"ts":1425054123486,"service": {"service":"example01","type":"rest","route":"/heartbeat"}}

Using the service APIs

Having checked the health of the service, let's invoke the remaining APIs.

Each of the service's APIs requires the following set of inputs:

Parameter	Mandatory	Type	Source	Format
firstName	YES	String	Query String	N/A
lastName	YES	String	Query String	N/A
email	NO	String	Query String	Email only

"testGet" API: Failure

The first API to test is the "TestGet". In this scenario, the request is sent with only the "firstName" input. The request does not contain the second mandatory input: "lastName". So we expect the response to return with an error.

TestGet request: Missing Last Name

curl -X GET "http://127.0.0.1:4021/testGet?firstName=John"

As expected, the API returned an error response. Since "lastName" is a required field and is missing in the querystring, the IMFV stopped the request returned an error response.

TestGet respone: Missing Last Name

{"result": false,"errors": {"codes": [172],"details": [{"code": 172,"message": "Missing required field: lastName"}]}}

"testGet" API: Success

In this scenario, the request is sent with all the required input. The response should be a a JSON object containing the searched for object.

TestGet request: Success

curl -X GET "http://127.0.0.1:4021/testGet?firstName=John&lastName=Smith"

As expected, the response returned is a JSON object containing the searched for object.

TestGet Reponse: Success

{"result": true,"data": {"firstName": "John","lastName": "Smith"}}

"testPost" API: Success

This API is exactly like testGet but uses the "post" method.

TestPost request: Sucess

curl -X POST -H "Content-type:application/json" -H "Accept:application/json" "http://127.0.0.1:4021/testPost" -d '{"firstName":"John","lastName":"Smith","email":"john@smith.com"}'

As expected, the response returned is a JSON object containing the searched for object.

TestPost response: Success

{"result": true,"data": {"firstName": "John","lastName": "Smith","email": "john@smith.com"}}

"testPost" API: Failure

This request fails because of the invalid firstName "johnx" (Instead of "john"). This restriction is specified in the service itself.

TestPost request: Failure

curl -X POST -H "Content-type:application/json" -H "Accept:application/json" "http://127.0.0.1:4021/testPost" -d '{"firstName":"Johnx","lastName":"Smith"}'

As expected, the response returned an error.

TestPost response: failure

{"result": false,"errors": {"codes": [900],"details": [{"code": 900,"message": "firstName not found"}]}}

"testPut" API: Success

SOAJS also provides supports the PUT method:

TestPut request: Success

curl -X PUT -H "Content-type:application/json" -H "Accept:application/json" "http://127.0.0.1:4021/testPut" -d '{"firstName":"John","lastName":"Smith"}'

TestPut response: success

{"result": true,"data": {"firstName": "John","lastName": "Smith"}}

"testDel" API: Success

SOAJS also provides supports the DEL protocol:

TestDel request: Success

curl -X DELETE "http://127.0.0.1:4021/testDel?firstName=John&lastName=Smith"

TestDel response: success

{"result": true,"data": true}

"buildName" API: Success

This API receives a "firstName" and a "lastName" parameters, and returns the resulting fullName. However, the "firstName" parameter is not required, and if it is not sent within the request, the API has a default value to replace the missing one.

In this first request, both "firstName" and a "lastName" parameters are supplied.

BuildName request: Success

curl -X GET "http://127.0.0.1:4021/buildName?firstName=James&lastName=Smith"

The resulting response displays the fullName corresponding to the parameters given in the request.

BuildName response: Success

{"result": true,"data": {"fullName": "James Smith"}}

"buildName" API: Success (No FirstName Parameter)

In this test, the "firstName" parameter is not supplied. However, since the API is configured to fallback to a default value, no error response is generated. Rather, a response containing the default "firstName", in addition to the "lastName" supplied by the request, was generated instead.

BuildName request: Success

curl -X GET "http://127.0.0.1:4021/buildName?lastName=Smith"

BuildName request: success

{"result": true,"data": {"fullName": "John Smith"}}

Browser not supported