Data Mapping REST Web Services

MapForce 2016 Release 2 includes expanded functionality for Web Services data mapping, providing robust support for REST Web services. MapForce accepts XML or JSON as the Web service response, allows definition of parameters, and supports custom HTTP headers. Users may define the Web service interface manually or by importing settings from a WADL file or a URL. Manual definition of REST Web Service Settings lets developers create settings based on a template URL. This is a convenient step when developers test and refine REST calls in a Web browser window, since the URL can be copied from the browser to become the template.

REST Web Services can be a pipeline of information for a data mapping project

We’ve noted previously that coordinates captured by GPS systems are precise, but elevation data is notoriously inaccurate. The USGS provides a REST Web service that accepts queries providing longitude and latitude and supplies accurate elevation data, either in XML or JSON. We can use this Web service in a MapForce data mapping to update GPS data from a Garmin device and simultaneously convert the data format from XML to JSON.

We’ll start by testing the Web service in a browser window. The URL shown below opens an input form to generate a sample query:

Input form for a single elevation point query

When we click the Get Elevation button, the form generates a complete REST GET query, submits it, and displays the result below. We can use this result to model the response for our data mapping.

Point query result in JSON format

We’ll add the Web service to our mapping by clicking the Insert Web Service Function button in the MapForce toolbar. This opens the Web Service Call Setting dialog, where we provide the URL of the USGS service.

Portion of the MapForce REST Web Services dialog to specify the service URL

Next we need to define the request parameters and the response body, which will create the elements for mapping, as seen below in the next portion of the Call Settings dialog.

Portion of the MapForce REST Web Services dialog to define request and response structures

We conveniently generated a JSON Schema in XMLSpy to define the response, based on the JSON instance file saved from the browser window. Shown below is the XMLSpy Schema view of the converted response:

XMLSpy Schema view of the JSON scema for the query response

The USGS elevation service input form gave us all the information we need to define the input parameters, so we can add those to the next section of the Call Settings dialog:

Portion of the MapForce REST Web Services dialog to specify query input parameters

The units and output values for each request won’t change during execution and we could have specified fixed values. Instead, we’ll provide them in the mapping as constants. Any necessary security settings would also be configured in the Call Settings dialog. When we click Okay to close the dialog, the Web Service function is added to the mapping.

The USGS elevation query as a function in the MapForce data mapping design

Each trackpoint in the source GPX file will provide a set of input coordinates. During mapping execution, a Web Services GET request will query the USGS every time a trackpoint is processed and the response will provide replacement elevation data.

Now all we need to do is connect elements of the request and response to input and output components, as shown below. The constants for units and output type are seen at the top left, and the elevation value is rounded to two decimal places before insertion into the output.

The USGS elevation query in the MapForce data mapping design with inputs and outputs connected

Note that the output is a JSON file. The input component is not shown in this partial view of the mapping, but it is an standard GPX file in XML format. The data mapping connection lines entering from the left, that pass behind the Web Service function in the illustration and connect to the output component are all values that will be copied without change from the XML input to the corresponding JSON elements.

When we click the MapForce Output button, the mapping executes and a JSON file is generated, as seen in the partial view here:

Partial view of the MapForce data mapping output as a JSON file

In a production environment we could save the mapping as a MapForce Execution File for automated processing by MapForce Server, either from a command line or under control of FlowForce Server.

Altova MapForce is an award-winning any-to-any graphical data mapping, conversion, and integration tool that maps data between any combination of XML, database, EDI, XBRL, flat file, Excel, JSON, and/or Web service. Download a fully-functional free trial and check it out for yourself!

Tags: , , , ,