Here I’ll walk you through the process of creating a simple Node/Express API and connect it to a InterSystems IRIS instance.
I won't go into much detail about how to work with any of the technologies I will mention in this tutorial but I will leave links, in case you want to learn more.
The objective here is to give you a practical guide on how to set up and connect a node.js back-end API to IRIS.
Before we get our hands dirty, make sure you have Node.js running on your machine. So I'll check:
Version 8.12.0 is the current LTS (Long Term support) version of node.js.
In case you have to install it go to https://nodejs.org.
Create the Main Project directory
In your terminal, navigate to a directory where you would like to save your project. Now create a new directory for your project and navigate into it:
Create an Express App
Ok, this will be as straightforward as the previous example. Don’t forget to navigate to your project top folder.
I will be using the Express Application Generator to quickly create an application skeleton and name it api:
Let’s see what I have done:
- Used npm’s npx to install express-generator globally.
- Used express-generator to create an express app and named it api.
- cd into the API directory.
- Installed all dependencies.
- Started the app.
In your browser, navigate to http://localhost:3000/.
If all is ok, you will see the express welcome page. Congratulations! That means you now have a basic Express application running on your local machine. Easy right?
To stop your express app, just press `Ctrl + c` in your terminal.
Install the InterSystems IRIS node adaptor
npm get all the packages for you except
iris.node that must be copy manually. So you should copy the iris.node file to
/node_module/iris directory (create it if not exists).
You can get iris.node from WRC or also from the
/bin directory of a InterSystems IRIS installed instance. Be careful and check if the copied file is the right version for your node installation. In my case I used node version v8.12.0 so I needed iris800.node. Remember to rename the file to iris.node.
You can get more detail about InterSystems IRIS node adaptor and versions here:
Configure the Database Connection
Well, we can solve this question in many differents ways, but do it simple. Create a new file
db/database.js and write this inside:
With this only three lines we are making "public" to the rest of components a reference to a InterSystems IRIS connection.
Open the Database Connection
Now, we are ready to tell to our Express server that opens the connection when is started. In order to do this we are going to edit the file
In any place of this file we can write:
Here we are declaring two objects, first object is the Database reference (from the file we build just a moment ago) and second object is an object containing the necessary data to open the connection (change to fit your needs, user, password, namespace, etc.).
After that, modify the
onListening function in this way:
We are just opening the connection to the database once the Express server is up and ready to listen.
You can start the server after that and check if we get the pretty message "IRIS connection opened!" in that case well done!!
Go for a coffee if you want you deserve it!!
Let's go for more
How was the coffee? good? well is the right time to go for more fun.
When the server is running what happen when you open a browser and go to http://localhost:3000/users/?
Yes, you see the message "respond with a resource". What a heck? from where it's coming?
I try to explain it. Express use Routing to decide how an application's endpoint (URI) respond to client requests (more info here http://expressjs.com/en/guide/routing.html) and... ok better take a look to the code ... If you open
app.js you can see a line like this one:
and later something like:
With that lines we are telling to Express that every request to path
/users must be route to the code in
/routes/users.js. So let's go to that file and review it. Look this function:
Not so complex right? What if we use this function and get some data from the InterSystems IRIS instance?
Add this line at beginning of the file:
And rewrite the method like this:
This method now will returns the value inside the InterSystems IRIS Global
Super!! we are almost done. Write something at this global opening a terminal session in IRIS. Something like:
Use the browser and go again to http://localhost:3000/users/. What happen now?
Yes!! You did it!! Do the victory dance !!
Did you enjoy?
Of course, this project as it is won’t do much, but is the start of a Full Stack Application.
If you want to get more of this, give me one star any comment and I'll make you the Master Developer of Full Stack Cosmic Applications ever!!!