Example: Calling a REST-Style Web Service
This example shows you how to call a generic HTTP Web service from MapForce. The description of the Web service called in this example can be found at https://app.swaggerhub.com/apis/FAA/ASWS/1.1.0. This Web service returns the current status of any major US airport, as an XML or JSON structure, accepting the three-letter airport code as argument (for example, "SFO", "IAD", "ABE", "DFW", etc). The example is accompanied by a mapping design file, which is available at the following path: <Documents>\Altova\MapForce2023\MapForceExamples\AirportStatus.mfd .
In this example, the response of the Web service is in JSON format, and is mapped to a JSON file. Therefore, the JSON schema of the Web service response structure will be required. For convenience, the JSON schema was generated with XMLSpy from a sample response supplied by the Web service provider. It is available at the following path: <Documents>\Altova\MapForce2023\MapForceExamples\AirportStatus.schema.json.
For the request part, we are going to call the Web service with a parameter which will supply the value "SFO" in the request. For the response part, we will map the response data to a JSON file. Therefore, the mapping will consist of three main components: the Web service call, the input parameter, and the JSON output file.
Step 1: Add the Web service component
1.Make sure the transformation language of the mapping is BUILT-IN.
2.On the Insert menu, click Web Service Function.
3.Under Service Definition, click Manual.
4.Set the request method to GET and the URL to https://soa.smext.faa.gov/asws/api/airport/status/{airportCode}. The value within curly braces is a template parameter which will be replaced with the actual airport code at runtime (see Adding a Web Service Call (REST-Style ).
5.Click the Add Parameter ( 
) button and add a new parameter to the "Parameters" table. Notice the name of the parameter must be the same as that of the parameter specified within curly braces in the URL. Set the style to "Template", type to "String", check the "Mappable" and the "Required" option. The "Description" field is optional.
6.Add a header to tell the Web server that the client (that is, MapForce) expects JSON in the response. To do this, click again the Add Parameter ( ) button, name the parameter "Accept", set the style to "Header" and enter application/json as fixed value.
7.Under Response, click the Edit button and browse for the schema of the Web service response. The schema can be found at the following path: <Documents>\Altova\MapForce2023\MapForceExamples\AirportStatus.schema.json.
8.Click OK. The Web service is now available on the mapping area.
Step 2: Add the input parameter
1.On the Insert menu, click Insert Input.
2.Enter "airportCode" as parameter name and click to clear the Input is required option (since the input will be supplied by a constant, as shown in the next step).
3.Add a constant (using the menu command Insert | Constant) with value "SFO" and connect it to the parameter input.
4.Connect the output of the aiportCode parameter to the input of the request, as shown below.
At this stage, the request part of the Web service is ready. At mapping runtime, the Web service will be called with the value provided by the constant (in this case, "SFO").
Step 3: Add the JSON output
1.On the Insert menu, click JSON Schema/File.
2.Browse for the <Documents>\Altova\MapForce2023\MapForceExamples\AirportStatus.schema.json, and click Open.
3.When prompted to supply a sample JSON file, click Skip (there is no need for a sample JSON file since it will be generated).
4.On the Connection menu, make sure that the Auto Connect Matching Children menu item is enabled. Enabling this option saves you time with the next step.
5.Connect the object node of the response body of the Web service to the object node of the JSON component, as shown below. Since the Auto Connect Matching Children was enabled in the previous step, all descendent nodes are connected automatically, so you don't need to draw individual connections for each.
Step 4: Execute the mapping
You are now ready to call the Web service. Click the Output button to execute the mapping and preview the generated output. If the Web service call is executed successfully, the Output pane displays the returned JSON structure. If the call is not successful, MapForce will return the error accordingly. As stated in the description of the Web service, the HTTP code 500 may be returned by the Web service in the case of error response. You may also get the HTTP code 404 if the requested information has not been found.
If you have MapForce Server, you can also compile the mapping to a mapping execution file (*.mfx) and execute it from the command-line or from the MapForce Server API on the server machine where MapForce Server runs (see Compiling Mappings to MapForce Server Execution Files ).
You have now finished creating a generic HTTP Web service call that uses a GET method to retrieve airport status data in real time. For more information about working with generic Web services, see also Adding a Web Service Call (REST-Style).