RESTful Service
Overview
There are a large number of information resources useful to applications beyond traditional databases. Many of these information resources are Internet accessible. Representational state transfer (REST) is a common pattern for interacting with these resources. A discussion onREST can be found at https://en.wikipedia.org/wiki/Representational_state_transfer. In general there is a known URL which may accept additional parameters to obtain some well described data.
Sample RESTful Service
Here is an example of a RESTful endpoint that returns a list of phone accessories
This example endpoint requires a “data” parameter which is the name of a data file. Sample results are shown below.
The source code for this sample data service is in ˜/qarbine.service/sample/restDataService.
RESTful Service Configuration
Some RESTful services require an API key or other authentication technique.
Here is an example of a RESTful URL that obtains the weather forecast given a longitude and latitude.
https://www.7timer.info/bin/astro.php?lon=113.2&lat=23.1&ac=0&unit=metric&output=json&tzshift=0
It returns a JavaScript Object Notation (JSON) string which can be parsed out as shown below.
The longitude and latitude could be variables that are filled in by a prompt or passed in from a calling application.
Qarbine Configuration
Compute Node Preparation
Determine which compute node service endpoint you want to run this data access from. That URL will go into the Data Service’s Compute URL field. Its form is “https://domain:port/dispatch”. A sample is shown below.
The port number corresponds to a named service endpoint configured on the given target host. For example, the primary compute node usually is set to have a ‘main’ service. That service’s configuration is defined in the ˜./qarbine.service/config/service.main.json file. Inside that file the following driver entry is required
"drivers" :[
. . .
"./driver/filteredRestDriver.js"
]
The relevant configuration file name for non primary (main) Qarbine compute nodes is service.NAME.json. Remember to have well formed JSON syntax or a startup error is likely to occur. If you end up adding that entry then restart the service via the general command line syntax
pm2 restart <service>
For example,
pm2 restart main
or simply
pm2 restart all
Data Service Definition
Open the Administration Tool.
Navigate to the Data Services tab.
A data service defines on what compute node a query will run by default along with the means to reach to target data. The latter includes which native driver to use along with settings corresponding to that driver. Multiple Data Sources can reference a single Data Service. The details of any one Data Service are thus maintained in one spot and not spread out all over the place in each Data Source. The latter is a maintenance and support nightmare.
To begin adding a data service click
On the right hand side enter a data service name and description. Next indicate the default compute node URL from which to run the data requests. For example,
Also choose the “Filtered_REST” driver.
The driver options are allowOtherUrls and rejectUnauthorized. If you want to allow arbitrary endpoints other than the server template then set allowOtherUrls to true. If you want to enforce SSL certificate options then set rejectUnauthorized to true.
Enter the primary portion of the RESTful endpoint as shown below. Any parameters will be appended later when the call is being made.
Remember that the Qarbine host must have network connectivity to the given endpoint, not the web browser clients.
Some endpoints require an authentication token or API key as shown below.
You can reference environment variables using the syntax %NAME%. Any strings should be quoted and the key\value pairs separated by commas.
For an HTTPS oriented RESTful endpoint, the interaction will use the Qarbine host’s SSL certificate and key.
After you have entered the information, save the data service by clicking on the image highlighted below.
Next, if the RESTful endpoint allows a simple test with an argument of “passiveCheck=true” then click on the icon noted below.
The test reply is expected to be an object with a status field value of true and a data field of some value. That value is shown in the dialog.
The data service will be known at the next log on time.
References
Useful links include