In this code pattern we will build a Node.js backend application on z/OS. The application accesses information that resides on z/OS and provides an API that can later be consumed by frontend applications and services. This code pattern will highlight the benefits of hosting the Node.js application on z/OS and will provide an introduction to Node.js development for traditional z/OS developers.
Node.js is a very popular platform for developing scalable enterprise API tier. Built upon the JavaScript programming language, Node.js enables millions of developers to build and collaborate across frontend and backend aspects of an application. Furthermore, the Node.js community has and continue to develop a plethora of frameworks and modules to enable rich web applications. In this code pattern, we will focus on one such open-source framework - LoopBack. LoopBack is a highly-extensible, open-source framework, that allows you to create end-to-end REST APIs with minimum coding effort. It allows for agile development and quick iterations for expanding and growing an enterprise solution. As Node.js is platform neutral, the development can be done on any platform independent on the deployment. Node.js on z/OS is now a first-class enterprise offering, making it ideal for hosting backend applications which require access to z/OS assets while providing performance, scalability and security. In this code pattern we showcase the business challenges that a typical customer on IBM Z might experience. We share a case study about a fictitious TorCC credit card company, and how they leverage the capabilities of the z/OS system.
The TorCC credit card company provides a complex reward system as incentive program for its customers. It allows members to share their reward points. The company wishes to create a backend application that provides an API to query the status of the reward program, based on the member name or set of names. The resulting API can then be used by web or mobile applications (the frontend). It can also be used by other frontend applications, for example, to create internal reports or use analytics to provide recommendations to the members.
The objective of this application is to enable a highly scalable set of APIs that can support large volumes of concurrent transactions, while ensuring that confidential information, such as customer and credit card data, are never exposed to an external network or cloud. Given the massive volume of data and transactions TorCC credit card company handles, they host the data on z/OS. To provide best security and performance, the company decides to host their backend application on the same system, the z/OS system, where the data resides. Co-location of the application with the data allows TorCC credit card to take advantage of the high levels of performance, reliability, security and scalability that z/OS provides, while also benefiting from improved response time and throughput performance accessing the data. With sensitive or confidential data hosted on z/OS, co-locating the application on the same platform reduces the risk of data breaches, and avoids the monetary costs of ETL'ing the data. If the APIs are well designed, there will be no confidential communication exposed on the external network between the frontend and the backend.
In addition, having the backend application on the same system as the data will also reduce cost of power, footprint, cooling, and decrease system complexity and management efforts, compared to a solution on a remote or distributed system.
When you complete this pattern, you will understand how to:
- Install node.js on z/OS
- Implement and deploy a node.js application using Loopback for API access
The backend server communicates with data assets on the z/OS system and generates 4 APIs to query and manage the reward program.
- Create a Node.js rewards program application with LoopBack framework.
- Deploy the Node.js application on z/OS to benefit from collocation advantages such as performance and security.
- Expose the rewards program APIs. The credit card and customer info remains secure in the z/OS.
- Explore, test and consume the APIs created.
- LoopBack: A highly extensible, open source Node.js framework.
- Node.js: An open-source JavaScript run-time environment for executing server-side JavaScript code.
- Systems: Systems have to be flexible to support new types of applications and solutions.
Node.js
Node.js is the server-side JavaScript platform. If you do not have Node.js installed, you can find the installer for your platform at Node.js. For z/OS see IBM SDK for Node.js on z/OS. Please note, you can get a free trial version of Node.js on z/OS for testing at free 90-day trial (SMP/E format) with installations instructions here or at Node.js SDK on z/OS trial (pax format) (downloads and instructions). Please follow the installation instructions provided, in particular for the pax format trial version.
Verify installation with:
node --versionLoopBack
LoopBack is an open-source framework to rapidly build APIs in Node.js. To install LoopBack type the following:
npm install -g loopback-cli # Install the Loopback Client
lb -v # Print Loopback version to validate client installation.Git
Git is a distributed version control system. You can get git for z/OS from Rocket Software..
cURL
cURL is command line tool for transfer data in different protocols. You can get cURL for z/OS from Rocket Software..
This section provides introduction experience into Node.js, to showcase the ease of writing Node.js applications and to familiarize with LoopBack concepts and components. It provides a couple of paths of engagement designed for different levels of experience.
In our scenario, the TorCC credit card company holds data regarding the members, the credit cards and the reward programs. It provides a rewards program in which multiple members share the reward program. TorCC wants to expose APIs for frontend or mobile usage, to query and manage the reward program. In our example, we generate 4 APIs to deal with the rewards programs:
- create a program
- query the status
- delete/close a program
- claim points
These APIs cover the full spectrum of create, retrieve, update and delete (CRUD) functions.
While this code pattern targets z/OS users, you can create and run the application on any platform, in particular as our example data resides in memory, and is not tied to the platform. In practice z/OS customers probably have their data reside in DB2 or other asset on z/OS and thus will benefit from deploying the backend application on z/OS and collocating the application and the data.
The first part provides basic steps to run the application as is and get familiarized with the APIs. Deploying it on a z/OS system would demonstrate that Node.js on z/OS is a first class citizen and it behaves similarly to any other platforms. By the end of this part, you will have setup your environment and know how to run a Node.js application and how to explore its APIs.
The second part guides you through the steps to recreate our rewards application. It provides basic information about LoopBack concepts such as datasources, models and relations. By the end of this part you should have the knowledge to create your own simple LoopBack application.
To experience with the rewards application, ether by running it or creating it yourself, you first need to clone the repository locally.
git clone https://github.com/IBM/loopback-demo-zosOn z/OS run the following:
git clone git://github.com/IBM/loopback-demo-zosAlternatively, download the code pattern as a zip file from here. On z/OS, use 'unzip -a' to unzip
This part guides you through the steps to run the application and explore the APIs and test the application. By the end of the session you will understand the APIs and be able to explore and test the APIs created.
In the code pattern directory, install the node module dependencies with npm, and run the application.
cd loopback-demo-zos
npm install
node .The output shows the customers, credit cards and rewards program created. It will also include the following lines:
Web server listening at: http://0.0.0.0:3000
Browse your REST API at http://0.0.0.0:3000/explorerThe application launches a http server listening on the default port 3000. You can explore your REST APIs created at http://localhost:3000/explorer. This URL lists all the APIs exposed by the application and available for use. In the explorer, you can expand the APIs by selecting List Operations to see its details and also test them.
To test a specific API from the web browser, append the API name followed by the parameters in JSON format to the base URL. In our example, the base URL is: http://localhost:3000/api/Rewards. Alternatively, use the curl command from the command-line in another shell/terminal. You can also invoke the API remotely by specifying the hostname instead of localhost.
In our example, we provided 4 APIs to handle the rewards program: getPoints, claimPoints, createProgram and closeProgram. The parameters for those API is list of members in JSON format. The table below provides description of the expected parameters and some examples to follow:
You can test these APIs as follows:
-
createAccount
curl -X POST -d "Members[]=Ross&&Members[]=Rachel" "http://localhost:3000/api/Rewards/createAccount" -
getPoints
curl -X GET -d "Members[]=Monica&&Members[]=Chandler" "http://localhost:3000/api/Rewards/getPoints"
You should see the amount of credit card rewards points that Monica and Chandler can redeem together:{'TotalPoints';:11500}
-
claimPoints
curl -X PUT -H "Content-type:application/json" -d '{"claimedPoints":[{"Name":"Monica","Points":"1000"},{"Name":"Chandler","Points":"100"}]}' "http://localhost:3000/api/Rewards/claimPoints"
You should see the amount of credit card rewards points remaining in the program:
{"Status":{"Status":"Success","RemainingPoints":10400}
-
closeAccount
curl -X DELETE -d "Members[]=Ross&&Members[]=Rachel" "http://localhost:3000/api/Rewards/closeAccount"
For the steps to create your own Rewards application, please follow this link to RewardsApplication.md.
- IBM SDK for Node.js – z/OS trial
- IBM SDK for Node.js - z/OS Knowledge Center: Overview, installation instructions, and troubleshooting tips for the IBM SDK for Node.js - z/OS
- IBM SDK for Node.js community: Forums and discussion around the IBM SDK for Node.js
- Reasons to Host your Node.js Applications on z/OS: A blog detailing the benifits of using z/OS
- z/OS Offers Co-Location and Technology Advantages: An IBM Systems Magazine article with a technology overview