Objective

Build a microservice using SOAJS Swagger Editor
Deploy micorservice and test it using Swagger Simulator and Postman
Quick look at Multitenancy and its impact on microservices' behavior

Scenario

Install SOAJS
Install Demo
Deploy Demo
Test Service
Sample Data Explained

1 - Installation

Start by installing and deploying SOAJS as a local Cloud; Click Here and you will be redirected to the SOAJS Installer Space where you can find the installation instructions. For this demo, we will be using Local Cloud Deployment on top of Docker.

Use the installer to install SOAJS, but do not login yet, this demo requires you to import some settings then it tell you when it is time to login.

2 - Install Demo

Clone the quick demo repository from github; it contains the code and a script that will bootstrap some database configuration for this demo ( explained below )

OSX Users

Make sure you have Xcode (or at least Xcode cli) installed to be able to use the "git" command from the terminal!

Fetch SOAJS demo repo

# Create a directory to clone the repo
> mkdir -p /opt/soajs/node_modules

# Go to directory
> cd /opt/soajs/node_modules

# Clone repo from github
> git clone git@github.com:soajs/soajs.quick.demo.git

# install dependencies
> cd soajs.quick.demo
> npm install

# Import the configuration
> cd soajs.quick.demo/import/

# node . -h <mongo service host> -p <mongo port>
> node . -h dashboard-soajsdata -p 32017

Import Script Help

# Open the import script help manual
> cd soajs.quick.demo/import/
> node . --help

Swagger Editor

From here on, we will use the SOAJS Dashboard UI to resume all the work. Log in to the SOAJS Dashboard and head to Develop pillar → Swagger Editor.

This Module provides the ability to create microservices using YAML code.

References:

Swagger: http://swagger.io
SOAJS Swagger Editor: Click Here

3 - Deploy Demo

3.1 Activate Demo Repo

Head over to the Develop pillar → Repositories to activate the quick demo microservice.

In Repositories, we find the default SOAJS account activated and it contains a list of repositories we can turn on and off.

Activate the soajs.quick.demo repository, you will be asked to select a branch; pick master.

3.2 Deploy Environment and Microservice

Our import script already imported the configuration we need to get things going. Let's deploy the DEV environment and the quick demo microservice.

Step 1: Deploy Environment

Go to Deploy pillar and select DEV from the drop down menu in the top left corner.

Click on Clouds & Deployments in the left-hand side menu, click on the Services tab and press Deploy Environment.

Step 2: Deploy Service

Make sure the selected environment is dev in the top left sidebar.

Navigate to Repositories under Deploy pillar, click on the service to deploy and press Configure Deployment, fill the form like the following picture and press First Time Deploy:

Once the environment is deployed, update your hosts file and add the below entry:

Point the Dev Domain IP in your hosts file

127.0.0.1	dev-api.mydomain.com

4 - Test the Microservice

4.1 Tools

We will test the microservice in two ways :

Postman: simulates your curl requests to test the microservice.
Import the postman collections from the postman folder in the repo you cloned above, you will notice two new collections:

demo_memory: contains 4 requests
demo_mongo: contains 2 requests

Postman is a GUI platform to make API development faster and easier. Download Postman for your OS here

2. Swagger Simulator: rich UI simulator that provides REST API documentation and the ability to interact with them.
SOAJS Dashboard UI is equipped with Swagger Engine and Simulator by default.

Go to the dashboard → Develop → Services:
Click on Swagger logo that appears if the microservice is created using Swagger Editor and a new tab will open
Choose your environment where you deployed your microservice
Use the simulator to make API calls to your microservice

Quick Demo APIs

Use POST /user/ as the first request to insert a user record.

Use GET /user/:id to retrieve a user record.

Use PUT /user/:id to edit a user record.

Use DELETE /user/:id to delete a user record

4.2 Tenant Keys

Quick Demo is a multitenant microservice; you will need to provide the tenant keys for the requests to work.

To find these keys, go to the Manage pillar → Multitenancy → Client ( you will see the list of tenants there ).

Expand a tenant entry, to reach the external keys section, grab the external key and use it in the postman requests.

5 - Sample Data Explained

In step 2, we imported some provision configuration, let's understand what this data is.

5.1 DEV Environment:

In order to deploy an environment like we did in the Step 3, you need to provide a configuration that contains how this environment should be deployed.
Yet in the Step 3, the DEV environment was already present when we opened the Deploy Pillar; it was part of the provisioned configuration that was imported.
Had we not imported it, we would have had to manually create it along with its configuration.

5.2 Productization & Multitenancy:

Similarly, we imported a product that provided ACL packages used in the DEV environment by some tenants; This also means we imported some tenants.
This effectively reduces the time it takes to get going with this demo as everything has been preconfigured.

SOAJS Layers:

Users and Groups belong to tenants.
Tenants use product packages and each tenant offers a custom configuration per environment.
Products and Packages provide ACL access to services
Services provide APIs and are deployed in multiple environments.

5.3 Showcase:

In our example, we have:

1 service with 4 APIs to manage users records:

API	Method	Description
/user/	POST	creates a new user record based on posted values in request body
/user/:id	GET	returns one user record based on provided id
/user/:id	PUT	updates a user record based on provided id and posted values
/user/:id	DELETE	deletes a user based on provided id

1 Product with 2 Packages:
Package Name Environment Description
package 1 DEV provides public access to all 4 APIs
package 2 DEV provides limited access to only GET and POST APIs

5 Tenants:

Tenant Name	Code	Package	Configuration	Description
Demo tenant 1	DETE	package 1	Memory	Tenant configuration instructs the service to use the memory to store and retrieve user records.
Demo tenant 2	DET1	package 2	Mongo Standalone	Tenant configuration instructs the service to use mongo database (demo_SA) to store and retrieve user records.
Demo tenant 3	DET2	package 2	Mongo Standalone	Tenant configuration instructs the service to use mongo database (demo_SA) to store and retrieve user records.
Demo tenant 4	DET3	package 2	Mongo Multitenant	Tenant configuration instructs the service to use mongo database (DET3_demo_MT) to store and retrieve user records.
Demo tenant 5	DET4	package 2	Mongo Multitenant	Tenant configuration instructs the service to use mongo database (DET4_demo_MT) to store and retrieve user records.

In the above configuration, tenant 1 uses the memory model, this means if the service is turned off, all data will be lost.

Tenants 2 & 3 use the same database to store and retrieve the information from a mongo database called demo_SA.

Tenants 4 & 5 each use a database based on their tenant code value to store and retrieve the information from a mongo database where the database name uses this format: %TenantCode%_demo_MT.

6 - Conclusion

To sums it up, this demo is a good introduction to learn how to build a simple microservice having the 4 essentials HTTP APIs using Swagger Editor.

In addition, it will guide you to deploy the microservice in DEV environment using the dashboard so you can test it in Postman or Swagger.

Finally, it will demonstrates the power of multitenancy by means of 5 tenants, where each tenant makes the service behave differently when it calls its APIs and the fact that you can build and apply custom and reusable ACL recipes on these tenants.

Browser not supported