This is a follow-up on a previous blog, NodeRun Restful Web Services: How do they Work?. In this blog, we’ll start creating RESTful web services on NodeRun. Our web service will retrieve a list of employee records.
** Important Note: Whenever working with web services, you will need a tool to test them using various HTTP methods. Browsers support GET methods out-of-the-box through the address bar, but browsers do not directly support PUT, DELETE, etc. There are many tools that can do this (I personally use Fiddler), but for this blog post I have chosen to use a Chrome add-on called Advanced REST Client (ARC) because it is small and simple to install.
Start with the REST Web Template in NodeRun
Let’s start out with the same template as used in the previous blog. You can view the Space I am working with in this example below.
I clicked “Create a New Space” in NodeRun and chose the “REST Web Services” template in the Designer. This template already has a couple Web Service examples built in, giving you the ability to retrieve a list of customers, as well as a database with tables and data. I published this Space just to be sure this template was in good working order, and we will change the application to fetch ‘Employees’ not ‘Customers’.
By launching the application, it opened a new browser tab with the heading of “Web Services Test”:
Write our Own Web Services
First, I needed a database table to get started. I clicked on the database tab and found a table named employees, so I decided to use it to create some of my own CRUD services with a couple of extras added along the way. I could have easily created new table(s) with data from here, but that is for another day.
Create a Service to Fetch a List of Employees
I have a little organizational OCD within me, so I created a folder called ‘Employees’ and within that folder I created a new file called ‘getEmployees.js’.
Next, I went to the properties of this get’Employees.js’ file and set up the service path:
From there, I:
- Checked the Express Route option
- Set the HTTP Method to GET
- Set the Route Path to employees
In the Advanced REST Client (ARC) Chrome add on, I chose GET in the Method field, changed the route in the Request URL field to match the /employees, and clicked the Send button.
Low and behold, it worked and was really easy! I got 23 employees shown in JSON.
But hold on – I created a new file and a new web service route, and I did not compile anything, nor did I restart any service. So how did it work?
- The framework supports a concept called hot-reloading, where the file(s) are only loaded when they are needed. If that file has changed since being loaded, it will get reloaded.
- The framework was also engineered to handle dynamic routing, so by altering the file properties dialog they are instantly applied.
Add a Couple of Bells and Whistles
Let’s say that you want to add the ability to filter results – for instance, filtering employees by their names. By using query string parameters, you can filter employees where their first name contains some value, and the expected RESTful URL should look like this: /employees?firstName=%mary%
I changed the ‘getEmployees.js’ file to account for the optional query parameter from the request object and inserted a WHERE condition into the SQL statement:
In ARC, I chose GET in the Method field, changed the query string in the Request URL field to ?firstName=%mary% and clicked the send button. It returned just the employees that have “mary” somewhere in their firstName column.
If you want to add a record limit and record skip option, you can also do this by way of query string parameters. This is so the resulting data is not thousands and thousands of records and allows the web service to be used to load one page at a time.
|The expected URL would look like:||Result:|
|/employees?limit=10&skip=0||(page 1 with 10 records)|
|then /employees?limit=10&skip=10||(page 2 with next 10 records)|
|then /employees?limit=10&skip=20||(page 3 with final 3 records)|
I changed the ‘getEmployees.js file’ to account for the optional query parameter from the request object and applied it to the SQL statement
In ARC, I chose GET in the Method field, changed the query string in the Request URL field to ?limit=10&skip=0, and clicked the send button. It returned the first ten employees. I changed the skip to 10 and clicked the send button, and it returned the second page of ten employees.
I played around with different combinations of these URL options, but as you might have gathered, there is so much more that you can do. For the more advanced developers, take a look at OData. There you can see a ton of options you can put into your query string to deliver almost SQL-like functionality via a URL.
In my next blog post, I’ll finish this series on RESTful web services by showing you how to call a single record, and to add, update, and delete records!