IBM Transformation Extender (ITX) can connect to many different "protocols", and versions starting from 184.108.40.206 are able to consume or provide services through OpenAPIs.
In this article, I'd like to give an introduction and a working sample of a "consumer" scenario.
The example used to write this article can be replicated using a developer key to consume OpenWeatherMaps service information.
A map calls a service from OpenWeatherMap.com, in this case current weather information for a given (hard-coded) city. As the site does not provide API specifications in the "Swagger" format, they were built for the purpose of the exercise.
It is assumed you are familiar enough with ITX in order to be able to accomplish normal ITX development tasks without detailed instructions.
To use the data consumption scenario, a developer key for the Openweathermap.com service is needed. To get it, navigate to the http://www.openweathermap.com site, then select "Signup".
Provide identification information, the create the account. Navigate to the "API keys" tab, then provide a name for a new API key and click "generate".
A new key is generated. You will later be able to use it when needed.
ITX design studio installation
Make sure you have a 220.127.116.11 or higher version installed, as this is the version which brings the OpenAPI importer functionality, which you'll need to implement the scenarios. The version is available via FixCentral. You can check the installed version by clicking "Help / About IBM Transformation Extender Design Studio".
The pop-up window below shows 18.104.22.168 version is installed. The number between parentheses is the "build number", which could be used to track a more specific version.
Note that, unlike earlier versions, 22.214.171.124 and above require you to remove the previous version before installing, as it does not support installing "on top" an existing 9.x version.
The only needed file to replicate the exercise is the JSON file whose content is shown below. Simply copy and paste the contents in a text file named MyOpenWeather.JSON. This file was developped to define the APIs from OpenWeatherMap.org, as the site does not provide a downloadable specification. You can click anywhere in the file below for the ability to download the document as an attachment.
In this "exercice", we will:
- import the Swagger specicationsle to generate a type tree
- create a map calling OpenWatherMap to get the current weather infos about an abritrary city
- run the map and check the results
Importing the type tree
The JSONfile describes the expected parameters and information returned for the "current" API from OpenWeatherMap.org, as shown here: https://openweathermap.org /current. Although the API can work based on several parameters combinations, our example is restricted to using a named city. The only operation is a GET, since we are only consuming information.
In a newly created ITX project, select the Import menu, then the OpenAPI option.
Select the MyOpenWeather.jsonfile you created previously.
Click Next to choose import options.
Click Next, then select the "Use IBM Tranformation Extender to call the REST API"
option. This will generate the type tree as well as the map to call the API. The other option
will be discussed in a following chapter.
Click Next, then review the connection information.
Click Next again to review and set the importer's options. To generate the sample map, select the Generate sample map source box.
The file is imported, and the type tree is generated as a result. The results window shows there were warnings during the importation process. We'll ignore them as they have no influence on our exercise.
Terminate the importation by clicking Yes as an answer to the "Would you like to open the type tree now?" question.
Type tree review
When the type tree opens, it has all the structure open. It is usually easier to start by a more compact view. To do so, simply double-click on the "OpenAPI" root category, the double-click again.
The "OpenAPI" root category indicates the type tree was imported using the "OpenAPI" importer. If you look at the "Request" category, you'llnd the "GET" group, which is the calling structure to the API. This group is pretty simple here, since all the information we pass will be passed through the REST call.
Obviously enough, if you look at the "Response" category, you'llnd another "GET" group, which is the structure of the results from the API. This group is pretty simple here, as the only answer that was documented in the JSON e is the 200 "Success" one, and there were no alternative response structure documented.
Going deeper in the response structure, you could recognize the different data elements as documented by the OpenWeatherMap.org site.
Now, open the map called MyOpenWeather-GETSampleMap.mms.
The map has no inputs as it is no more than a sample map, and has 3 output cards, which prepare and execute the http call to get the information. If you compîle and run the map, it completes successfully. (Note that there could be a warning about the type tree not being analysed. Ideally, you hould analyse and save the type tree in order to avoid the warning. Alternatively, click "Yes" to say you want to compile anyway. Since the type tree was generated, the risk is very low.) However, if you look at the results for output card #2, you'll see it says HTTP/1.1 401 Unauthorized, which is the result of the http call failing, and so the mapping rule returns the resuts of a call to LASTERRORMSG, as instructed by the VALID call.
The mapping rule is built on the GET function to call the http adapter, and passes it the header prepared in card #1, along with some connection options. These options define the URL to send the call to (-URL), the method to be invoked (-METHOD), as well as some adapter-specific options (-TV -HDR -TYPE -STATUSLINE).
We could examine the http adapter's trace in order to investigate the error, as the -TV option gathers all trace information from the adapter. In this cas, however, the message is self explanatory: as we did not provide any credentials, the target site rejected our query. The trace file is m4http.mtr in the same directory as the map. Fixing the error involves providing a valid key ( appid parameter ) as well as a city name ( q parameter). Thefixed rule is as shown below, replace the obscured key with your own API key.
|=VALID( GET( "HTTP" , "-URL http://api.openweathermap.org/data/2.5/weather?q=Paris&appid=********************** -METHOD GET -TV -HDR+ -TYPE application/json -STATUSLINE", PACKAGE(httpRequest)), LASTERRORMSG() )|
Once the rule has been fixed, the map will start returning useful results. It's worth noticing that, although the map has no input cards, the results pop-up shows 24 input objects. This is a result of the use of the PARSE function in card #3.
The last card uses the GET group from the "Response" category to collect the results, and the PARSE function is used to get the raw results from card #2 in a structured form, for further use as needed.
The results show some current information about the weather in the choosen city.