Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...

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.

...

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

...

Code Block
languagebash
titleRunning the service
linenumberstrue
# go to correct directory examples/example01 and start the service
cd /opt/soajs/node_modules/soajs.examples/example01/
 
# start the soajs example environment
sudo soajs services start --env=example
 
# export necessary environment variables to create local awareness
export SOAJS_PROFILE=/opt/soajs/node_modules/soajs.utilities/data/getStarted/profile.jsENV=EXAMPLE
export SOAJS_SRVPORT=4021
export SOAJS_ENVDEPLOY_MANUAL=test1
export SOAJS_SRVIPREGISTRY_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 40104021.

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.

...

Code Block
languagebash
titleHeartbeat
linenumberstrue
curl -X GET "http://127.0.0.1:50105021/heartbeat"

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

Code Block
languagejs
titleResponse
{"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.

...

ParameterMandatoryTypeSourceFormat
firstNameYESStringQuery StringN/A
lastNameYESStringQuery StringN/A
emailNOStringQuery StringEmail 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.

Code Block
languagebashjs
titleTestGet request: Missing Last Name
curl -X GET "http://127.0.0.1:40104021/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.

Code Block
languagejs
titleTestGet respone: Missing Last Name
linenumberstrue
{"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.

Code Block
languagebash
titleTestGet request: Success
linenumberstrue
curl -X GET "http://127.0.0.1:40104021/testGet?firstName=John&lastName=Smith" 

...

Code Block
languagejs
titleTestGet Reponse: Success
linenumberstrue
{"result": true,"data": {"firstName": "John","lastName": "Smith"}}

"testPost" API: Success

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

Code Block
languagebashjs
titleTestPost request: Sucess
linenumberstrue
curl -X POST -H "Content-type:application/json" -H "Accept:application/json" "http://127.0.0.1:40104021/testPost" -d '{"firstName":"John","lastName":"Smith","email":"john@smith.com"}'

...

Code Block
languagejs
titleTestPost response: Success
linenumberstrue
{"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.

Code Block
languagebashjs
titleTestPost request: Failure
linenumberstrue
curl -X POST -H "Content-type:application/json" -H "Accept:application/json" "http://127.0.0.1:40104021/testPost" -d '{"firstName":"Johnx","lastName":"Smith"}'

...

Code Block
languagejs
titleTestPost response: failure
linenumberstrue
{"result": false,"errors": {"codes": [900],"details": [{"code": 900,"message": "firstName not found"}]}}

"testPut" API: Success

SOAJS also provides supports the PUT method:

Code Block
languagebashjs
titleTestPut request: Success
linenumberstrue
curl -X PUT -H "Content-type:application/json" -H "Accept:application/json" "http://127.0.0.1:40104021/testPut" -d '{"firstName":"John","lastName":"Smith"}'

...

Code Block
languagejs
titleTestPut response: success
linenumberstrue
{"result": true,"data": {"firstName": "John","lastName": "Smith"}}

"testDel" API: Success

SOAJS also provides supports the DEL protocol:

Code Block
languagebashjs
titleTestDel request: Success
linenumberstrue
curl -X DELETE "http://127.0.0.1:40104021/testDel?firstName=John&lastName=Smith"

...

Code Block
languagejs
titleTestDel response: success
linenumberstrue
{"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.

Code Block
languagebashjs
titleBuildName request: Success
linenumberstrue
curl -X GET "http://127.0.0.1:40104021/buildName?firstName=James&lastName=Smith"

...

Code Block
languagejs
titleBuildName response: Success
linenumberstrue
{"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.

Code Block
languagebashjs
titleBuildName request: Success
linenumberstrue
curl -X GET "http://127.0.0.1:40104021/buildName?lastName=Smith"


Code Block
languagejs
titleBuildName request: success
linenumberstrue
{"result": true,"data": {"fullName": "John Smith"}}