Tips for calling an HTTP REST service
This page is legacy documentation. For the current HTTP REST connector, see its dedicated section. |
Sometimes, web service suppliers do not provide a WSDL. This is often the case when the web service consists in a simple HTTP GET Method.
This article shows how to call this kind of web service in Semarchy xDI, using a WSDL metadata.
The web service
We are going to work with the "OpenWeatherMap" web service for getting the current weather in a given city.
OpenWeatherMap is not a service supplied by Semarchy. |
-
The web service presentation: http://openweathermap.org/forecast
-
A sample request with an XML result: http://api.openweathermap.org/data/2.5/forecast?q=London&mode=xml&units=metric&APPID=YOUR_APP_API_KEY
-
The same one with a JSON result: http://api.openweathermap.org/data/2.5/forecast?q=London&mode=json&units=metric&APPID=YOUR_APP_API_KEY
Note that the request has parameters, especially the city name, the desired response format, and the API KEY.
You’ll have to create a free account on http://openweathermap.org/ to get your api key.
Creation of the WSDL metadata
Create a new Wsdl metadata file:
![http rest legacy.tips.newmetadata](../../../_images/base/wsdl/http-rest-legacy.tips.newmetadata.webp)
Under the Wsdl node, right click and create a Service node and a Port node.
The Wsdl node and the Service node only need the Name property to be set (for example "openWeatherMap" and "openWeatherMapService").
Here is the properties for the Port node:
-
Name: openWeatherMapHttpApi
-
Address: http://api.openweathermap.org/data/2.5
-
Protocol: HTTP
-
Http Verb: GET (if this property is not displayed, save/close/reopen your metadata first, this is a known issue)
![http rest legacy.tips.createPortNode](../../../_images/base/wsdl/http-rest-legacy.tips.createPortNode.webp)
Create a new Operation under openWeatherMapHttpApi:
-
Name: getForecastAsXml
-
Address: /forecast?q={cityname}&lang={lang}&units={units}&mode=xml&APPID=YOUR_APP_API_KEY
Note: If you want to use json change mode=xml to mode=json
![http rest legacy.tips.createOperationNode](../../../_images/base/wsdl/http-rest-legacy.tips.createOperationNode.webp)
Note the parameters in the URL: the curly brackets will help xDI know that these are placeholders for parameter values.
Declaration of the input parameters
Now, we need to declare the Input parameters of the service. For this, we create a new Input section, with 3 "Part" nodes:
![http rest legacy.tips.createCityPart](../../../_images/base/wsdl/http-rest-legacy.tips.createCityPart.webp)
![http rest legacy.tips.createLangPart](../../../_images/base/wsdl/http-rest-legacy.tips.createLangPart.webp)
![http rest legacy.tips.createUnitsPart](../../../_images/base/wsdl/http-rest-legacy.tips.createUnitsPart.webp)
Note: Instead of {params}
in the URL and http:urlReplacement
Binding type, we could use http:urlEncoded
Binding type. The parameters in this case are automatically added to the URL with the form ?<Name>=<value>&<Name>=<value>&...
Reversing the response in an output parameter
XML response
The web service response is in XML form, because we specified the XML mode. If you chose json mode, go to the next part.
We are going to reverse this XML and incorporate the result in our WSDL.
We will do that in three steps:
-
Retrieve the response in a file
-
Create a XML Metadata with this File
-
Copy the node we want from the XML Metadata to the WSDL metadata
1) Retrieve the response in a file
Retrieve sample response of a call to the web service, with going to this URL for example:
http://api.openweathermap.org/data/2.5/forecast?q=London&mode=xml&units=metric&APPID=YOUR_APP_API_KEY
→ Save the output in a File, you can name it openWeatherMapHttpApiOutput.xml.
2) Create an XML Metadata
Create a new XML Metadata, named xmlOutput, for example.
-
Use the file containging the response we retrieved for Default XML Path
-
generate an Xsd File, by clicking on the generate button, you can name it openWeatherMapHttpApiOutput.xsd
-
Then click refresh and select the good node, here 'weatherdata'
-
Click on reverse and Finish
![http rest legacy.tips.xmlWizard](../../../_images/base/wsdl/http-rest-legacy.tips.xmlWizard.webp)
You should have this:
![http rest legacy.tips.xmlOutputReversed](../../../_images/base/wsdl/http-rest-legacy.tips.xmlOutputReversed.webp)
If your location attributes (altitude, geobase, geobaseid, latitude and longitude) are reversed into the root/location element instead of root/location/location, this is a known bug. You can drag and drop them to the correct location to have the same thing as the screenshot. |
3) Create the web service Output parameter
Now, we are going to use the XML metadata we just created for the ouput parameter of our WSDL.
Open the web service metadata and create a new Output parameter
![http rest legacy.tips.newOutput](../../../_images/base/wsdl/http-rest-legacy.tips.newOutput.webp)
Create a new part in this Output, you can call it results
Next, create the root node of the results, by creating a new 'element' named 'weatherdata' on the results part.
Then, open the XML Metadata, and copy the sequence node
![http rest legacy.tips.copySequenceNode](../../../_images/base/wsdl/http-rest-legacy.tips.copySequenceNode.webp)
Finally, paste the Sequence in the weatherdata element of the WDSL.
You have now the output parameter of your web service, which you can use to get the result of an invocation of the web service in Mappings
![http rest legacy.tips.openWeatherMapMetadataFinal](../../../_images/base/wsdl/http-rest-legacy.tips.openWeatherMapMetadataFinal.webp)
JSON response
If you chose the json mode, reversing the response is very simple
Open the web service metadata
Create a new Output parameter
![http rest legacy.tips.newOutput](../../../_images/base/wsdl/http-rest-legacy.tips.newOutput.webp)
Create a new part in this Output, you can call it results
Next, right click on results and choose Launch JSON Object Wizard:
![http rest legacy.tips.launchJSONObjectWizard](../../../_images/base/wsdl/http-rest-legacy.tips.launchJSONObjectWizard.webp)
We will use a sample JSON Request URL to reverse the response:
![http rest legacy.tips.JSONWizard](../../../_images/base/wsdl/http-rest-legacy.tips.JSONWizard.webp)
Note:
-
Do not forget to click on Reverse
-
You could use too a Sample File (which contains the sample response) or Reverse directly from the Clipboard
Finished! You have now the output parameter of your web service, which you can use to get the result of an invocation of the web service in Mappings
![http rest legacy.tips.openWeatherMapMetadataJSONFinal](../../../_images/base/wsdl/http-rest-legacy.tips.openWeatherMapMetadataJSONFinal.webp)
Web service invocation
We are going to create a mapping which call the web service for a list of cities, fetched from the xDI Designer tutorial database.
Mapping overview:
![http rest legacy.tips.MappingGetWeatherOverview](../../../_images/base/wsdl/http-rest-legacy.tips.MappingGetWeatherOverview.webp)
A few comments:
-
The source table is T_ADDRESS, from the xDI Designer Demo database.
-
We added a filter for playing with only a few cities: T_ADDRESS.CUS_ID in (1, 10, 40, 50)
-
Note the "getForecast" node is a key node, it is required to set it, here we mapped it to the ADR_ID field.
-
We are using the metadata with the xml response, but for json the operation is the same
Integration Parameters:
![http rest legacy.tips.integrationOptions](../../../_images/base/wsdl/http-rest-legacy.tips.integrationOptions.webp)
-
Out File Name is used to indicate the file in which results will be aggregated
-
Sent Messages Folder is a folder in which the messages sent by the runtime to the web service will be stored (optional, usefull for debug, to see exactly what’s sent)
-
Received Messages Folder is a folder in which the messages received from the web services will be stored (optional, usefull for debug, to see the responses of the web services)
Using the result
Let’s see now how to use the output/response of the web service to load a table.
Mapping overview:
![http rest legacy.tips.MappingGetWeatherWithTargetOverview](../../../_images/base/wsdl/http-rest-legacy.tips.MappingGetWeatherWithTargetOverview.webp)
-
We are loading here the latitude and longitude of the T_ADDRESS Demo table from the web service.
-
Note that we use the getForecastAsXml node to map the T_ADDRESS_2.ADR_ID
Load parameters:
![http rest legacy.tips.loadParameters](../../../_images/base/wsdl/http-rest-legacy.tips.loadParameters.webp)
In File Name is used to indicate the file from which data will be loaded and must be set if a file has been entered in Out File Name property of the web service Integration template.