REST-based Web services have become massively popular - there is a Web service for just about anything you can think of. From credit card processing services, such as those available from Visa's VTC API, to blockchain services, real-time stock prices to address validation - there is probably a Web service that can help your NonStop application be more powerful and more relevant in today's world. But how do you enable your NonStop application to consume those services? LightWave Client can help.
This article will show you, step by step, how LightWave Client can be used with a simple NonStop demo program, to access Google's Geocoding API (https://developers.google.com/maps/documentation/geocoding/start). The blog can be read in conjunction with our YouTube tutorial, available at www.youtube.com/watch?v=dVzQw5t5lPA
The Google Geocoding API takes partial or complete addresses, completes them if necessary, and converts them into latitude and longitude coordinates, allowing them to be placed on a map, for instance. This API is available as a REST service, and as such, is a good candidate for consumption via LightWave Client from the NonStop.
This diagram gives a high level overview of the demo environment. On the left we have the "geocode" demo program, provided by NuWave, which gives a simple command line interface on the NonStop. Geocode communicates with LightWave Client via InterProcess Message (IPM). When a user enters an address into the geocode command line tool it is sent to LightWave Client. LightWave Client then builds a JSON request and sends it to the Google Geocoding API. The Geocoding service then converts that address into latitude/longitude coordinates and returns that data back to LightWave Client, which extracts the relevant data from the JSON response and sends it back via IPM to geocode. Geocode displays the information to the user.
The first step in getting this demo up and running is to obtain the latest LightWave Client software, and a trial license to run it. The NuWave software download center at https://docs.nuwavetech.com/display/DOCS/Software+Download+Center is the first port of call. Download the latest release of LightWave Client, then upload this PAK file to your NonStop and UNPAK it.
The Trial License Center (https://trial.nuwavetech.com/) is where you obtain a trial license for LightWave Client. Just enter a couple of details, including your system number, and the license will be generated for you. Download this license and place it on the same NonStop subvol as where you UNPAKed your LightWave Client software in the previous step.
Now we need to configure LightWave Client (LWC) to run in your environment. Edit the STARTUP file in the LWC subvol and update the LWC process name, the TCP/IP process name and set the console port to a port that is free on your system. Note that the TCP/IP process name will default if left blank.
Run the STARTUP file to start the LWC Console.
Then go to your browser, and enter the IP address and port that you just configured the LWC Console on. Login using the default username (admin) and password (password).
Once you have logged in, click on "APIs" on the left hand side, then click the "+" in the upper right to create a new API with the following information:
Click "CREATE" to create the new API, then click the "+" sign next to "Operations -- Paths and Methods" to create a new Operation Path, with a value "/maps/api/geocode/json":
Click OK to create the new Operation Path. Click the "+" sign next to the new Operation Path to add methods to it. Setup the following GET method:
Then click on the REQUEST tab to set the REQUEST message details. Note that we will come back to the Google API key later.
Click on the RESPONSE tab to set the response message mapping. Set the HTTP status as 200, then click "+" to add a new Data Mapping entry. At this point we need to obtain a sample JSON response from the Google developer documentation, so that we can add that sample to our response definition. Visit https://developers.google.com/maps/documentation/geocoding/intro to copy the sample JSON response:
and then go back to your LWC console to use this copied definition.
Paste the copied JSON into the Console field, then click OK to save the new definition. We have now created a new API schema, however a couple of fields in the schema need to be changed from their default values. Click on the "Edit API Schema" button in the top right to make these changes.
We then need to export this new API definition to the NonStop so that LightWave Client can access it. Click on "Export API Definition" in the top right to save the definition directly to an Enscribe file:
We now have LightWave Client installed, the Console is up and configured for the Geocoding API, and the API definition has been exported to the NonStop. We now need to download and install the demo "geocode" NonStop application. This is available on NuWave's Github repository at https://github.com/nuwavetech/lwc-geocode
Download this project to your PC, then follow the instructions in the README file.
Upload the PAK file to the NonStop, then UNPAK it.
TACL > UNPAK GEOPAK ($*.*.*), VOL $vol.subvol, LISTALL, MYIDBuild the application:
TACL > RUN LOADDDL
TACL > RUN BUILDCustomize and run the application:
TACL> T/EDIT SETENVChange the param "api-key". This will need to be set to a valid API key provided by Google - see https://developers.google.com/maps/documentation/geocoding/get-api-key for details.
TACL> RUN SETENV
TACL> RUN STARTPWAt this point all components should be up and running and you can now run the geocode command line utility:
Enter a complete or partial address and hit enter. The address information should be validated and returned, along with the latitude and longitude information:
You can see in the above example that the data has been return for "301 edgewater place wakefield MA" (NuWave Technologies' office address).
So we have now seen how to install LightWave Client, and configure it via the LWC Console to access the Google Geocoding API. We have also downloaded and installed the NuWave demo program "geocode" to send address information to the Google Geocoding API via LightWave Client. Chances are there is a REST-based Web service that would be beneficial to your NonStop application. Feel free to run this demo yourself, or get in touch with NuWave with your requirements so we can help you get setup with your own APIs.