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:

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)

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

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:

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

You should have this:

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

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

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

JSON response

If you chose the json mode, reversing the response is very simple

Open the web service metadata

Create a new Output parameter

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

We will use a sample JSON Request URL to reverse the response:

http://api.openweathermap.org/data/2.5/forecast?q=London&mode=json&units=metric&APPID=YOUR_APP_API_KEY

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

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

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

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

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:

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.