Using ITX9.0.0.1 with Open API

IBM Transformation Extender (ITX) can connect to many different "protocols", and versions starting from 9.0.0.1 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.

Scenario

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.

Prerequisites

It is assumed you are familiar enough with ITX in order to be able to accomplish normal ITX development tasks without detailed instructions.

Openweathermap

 

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".

Creating an OpenWeatherMap account

 

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".

Chap3_Createkey_01.png

A new key is generated. You will later be able to use it when needed.

 

Chap3_Createkey_02.png

ITX design studio installation

 

Make sure you have a 9.0.0.1 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".

 

Chap3_CheckDSVersion_1.png

 

The pop-up window below shows 9.0.0.1 version is installed. The number between parentheses is the "build number", which could be used to track a more specific version.

Chap3_CheckDSVersion_2.png

Note that, unlike earlier versions, 9.0.0.1 and above require you to remove the previous version before installing, as it does not support installing "on top" an existing 9.x version.

Downloads

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.

              {
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger OpenWeather API",
    "description": "Swagger 2.0 definition for OpenWeather API ",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "name": "Laurent"
    },
    "license": {
      "name": "MIT"
    }
  },
  "host": "api.openweathermap.org",
  "basePath": "/data/2.5",
  "schemes": [
    "http"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
    "paths":
    {
        "/weather":
        {
            "get":
            {
                "description": "Returns current weather for a named city",
                "produces": [
                  "application/json"
                ],
                "responses":
                {
                  "200":
                    {
                        "description": "Weather details",
                        "schema":
                        {
                            "type": "array",
                            "properties":
                            {
                                "coord":
                                {
                                    "type": "object",
                                    "properties":
                                    {
                                    "lon": {"type": "number"},
                                    "lat": {"type": "number"}
                                    }
                                },
                                "weather":
                                {
                                    "type": "object",
                                    "properties":
                                    {
                                        "id":{"type": "integer"},
                                        "main":{"type": "string"},
                                        "description":{"type": "string"},
                                        "icon":{"type": "string", "description": "Weather Icon Id"}
                                    }
                                },
                                "base":
                                {
                                    "type": "string",
                                    "description": "Internal parameter"
                                },
                                "main":
                                {
                                    "type": "array",
                                    "properties":
                                    {
                                        "temp":{"type": "number"},
                                        "pressure":{"type": "number"},
                                        "humidity":{"type": "integer"},
                                        "temp_min":{"type": "number"},
                                        "temp_max":{"type": "number"},
                                        "sea_level":{"type": "integer"},
                                        "grnd_level":{"type": "integer"}
                                    }
                                },
                                "wind":
                                {
                                    "type": "array",
                                    "properties":
                                    {
                                        "speed":{"type": "number"},
                                        "deg":{"type": "number"}
                                    }
                                },
                                "clouds":
                                {
                                    "type": "array",
                                    "properties":
                                    {
                                        "all":{"type": "number"}
                                    }
                                },
                                "rain":
                                {
                                    "type": "array",
                                    "properties":
                                    {
                                        "3h":{"type": "number"}
                                    }
                                },
                                "snow":
                                {
                                    "type": "array",
                                    "properties":
                                    {
                                        "3h":{"type": "number"}
                                    }
                                },
                                "dt":
                                {
                                    "type": "string"
                                },
                                "sys":
                                {
                                    "type": "array",
                                    "properties":
                                    {
                                        "type":{"type": "string"},
                                        "id":{"type": "string"},
                                        "message": {"type": "string"},
                                        "country": {"type": "string"},
                                        "sunrise": {"type": "string"},
                                        "sunset": {"type": "string"}
                                    }
                                },
                                "id":
                                {
                                    "type": "string"
                                },
                                "name":
                                {
                                    "type": "string"
                                },
                                "cod":
                                {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        }
    }  
}        

 

 Scenario implementation

 

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.

Chap4_2_ImportOpenAPI_1.png

 

Select the MyOpenWeather.jsonfile you created previously.

 

Chap4_2_ImportOpenAPI_2.png

 

Click Next to choose import options.

 

Chap4_2_ImportOpenAPI_3.png

 

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.

 

Chap4_2_ImportOpenAPI_4.png

 

Click Next, then review the connection information.

Chap4_2_ImportOpenAPI_5.png

 

Click Next again to review and set the importer's options. To generate the sample map, select the Generate sample map source box.

Chap4_2_ImportOpenAPI_6.png

 

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.

 

Chap4_2_ImportOpenAPI_7.png

 

Terminate the importation by clicking Yes as an answer to the "Would you like to open the type tree now?" question.

 

Chap4_2_ImportOpenAPI_8.png

 

 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.

 

Chap4_3_RevueMtt_1.png

 

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.

Chap4_3_RevueMtt_2.png

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.

Chap4_3_RevueMtt_3.png

 

Going deeper in the response structure, you could recognize the different data elements as documented by the OpenWeatherMap.org site.

Map review

 

Now, open the map called MyOpenWeather-GETSampleMap.mms.

Chap4_4_RevueMap_1.png

 

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.

 

Chap4_4_RevueMap_2.png

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).

Chap4_4_RevueMap_3.png

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.

Chap4_4_RevueMap_5.png

 

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.

 

Chap4_4_RevueMap_6.png

 

 The results show some current information about the weather in the choosen city.

Chap4_4_RevueMap_7.png

 

Conclusion

We have demonstrated how simple it is now to use ITX to consume Open API data, in order to integrate with services. The same scenario can be used to integrate OpenAPI calls to feed a map with data available for this protocol. The importer makes it easy to implement. Click here to download the zip file with the working solution.

1 Comment
2 Likes

ITX 9.0.0.2 example (using POST)

April 25, 2018 07:19 AM by Paul Brett
Recent Stories
IBM Recognized as Operations Leader for Seventh Consecutive Year

Using ITX 9.0.0.1 and Open API: Producer Scenario

Using ITX9.0.0.1 with Open API