Flink-ESB Message Gateway Tutorials

Use case: adding REST API to existing SOAP services using Flink-ESB Message Gateway

Original situation: application server offers SOAP services. Services can be called using HTTP POST.

Objective: add REST API in front of SOAP services, so that also REST clients, or any other client able to call HTTP GET, could consume the services

Estimated costs:

Programming efforts: 0

Administrator efforts: 10 minutes

Step 1: analyzing SOAP service to find out what variables it expects, and how it reacts on input error

Open http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?op=FullCountryInfo in the browser.

Take a look at the format of the SOAP request (let's take SOAP 1.1 for this tutorial). This request expects just one variable for the country code.

Go ahead and try different strings in the "Test" section on this web page. Try first DE, US. Click "Invoke" button and check the result.

Now try some incorrect data. For example, use 123 as country code and click "Invoke" button. Have a look at the error message. Now try empty country code, and check an error. Copy examples of the responses in case of correct data, and in case of error.

Step 2: defining façade entry for REST API

Open Flink-ESB Message Gateway Config Console in the browser. Default URL: https://localhost:8082. Login with default username/password: admin/admin

Click on "Gateway Config" tab if you are not there already, and press "Add Entry" button.

Enter data as on the picture below: "Config Id" : 1001 (or any unique Id), "Method" : GET, "URI" : /service/country/info/{country}. Leave all other fields with their default values.

By typing "{country}" you define this part of URL to be dynamic. It means, you can call "/service/country/info/DE" or "/service/country/info/US" or "/service/country/info/123", and all those requests will be handled by that façade entry. Flink-ESB would also add a message property with the name "country" (string you typed between curly braces), and a value, you entered in the URL instead of "{country}".

Check the data you've entered. Now click "Save Modifications" to save new façade entry

Step 3: defining a destination: URL where soap service can be called in Flink-ESB Message Gateway Config Console

Click on "Destinations" tab and click "Add Entry" button. Type data as on picture below: "Destination Id" : 1001 (or any unique Id), "Protocol" : HTTP, "Method" : POST, "Destination Expression" : 'http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso'.

Destination URL consists of Host header and URI found on soap service description page (see also picture in step 1). Since this URL is a literal value (contains no expressions or variables) - it should be enclosed in single quotes, as on picture above.

Pay attention, we've defined a destination HTTP POST (as description of the service requires), but façade entry serves HTTP GET requests. So we transform incoming HTTP GET requests into outgoing HTTP POST soap messages.

Now click "Save Modifications" to save a destination.

Step 4: defining a transformation rule for the request in Flink-ESB Message Gateway Config Console

Open URL http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso in a browser and copy a content of SOAP request body.

Now open a text editor and create a new file. Paste a content into that file, and do the modification as on the picture below:

Save a file in some folder. Give it a name "CountryInfo.template" (or any other name you wish).

Now go to Flink-ESB Message Gateway Config Console in your browser and click on "Transformation Rules" tab. Enter data as on the picture below: "Rule Id" : 1001 (or any unique Id), "Rule Type" : TEMPLATE, "Filename" : D:/programming/templates/CountryInfo.template (replace path with your local path, or better replace it with a project variable).

Now click "Save Modifications" to save a transformation rule.

Step 5: defining a message property for the request in Flink-ESB Message Gateway Config Console

Open URL http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso in a browser and copy a content of "Content-Type" header.

Now go to Flink-ESB Message Gateway Config Console in your browser and click on "Message Properties" tab. Enter data as on the picture below: "Property Id" : 1001 (or any unique Id), "Property Name" : Content-Type, "Property Expression" : 'text/xml; charset=utf-8' (this should be the same as the content of HTTP header you copied). !!! Do not forget to enclose a value of property in single quotes !!!

Now click "Save Modifications" to save a message property.

Step 6: assigning destination, transformation rule and message property to façade entry in Flink-ESB Message Gateway Config Console

Click on "Gateway Config" tab and click on the row with "Config Id" 1001 (or whatever Id you've assigned to GET façade entry) to unhide details panel.

Click on "Edit Destination Rules" link, select "Show all rules" checkbox and select a checkbox on the left side of destination with Id 1001 (or whatever Id you've assigned to SOAP service destination). Destination should change a colour from grey to black as on picture below:

Click on "Edit Destination Rules" link to hide details panel for the destinations. Now click on "Edit Request Transformation Rules" link, select "Show all rules" checkbox and select a checkbox on the left side of rule with Id 1001 (or whatever Id you've assigned to the rule in step 4). Rule should change a colour from grey to black as on picture below:

Click on "Edit Request Transformation Rules" link to hide details panel for the transformation rules. Now click on "Edit Request Properties Rules" link, select "Show all rules" checkbox and select a checkbox on the left side of property with Id 1001 (or whatever Id you've assigned to the property in step 5). Property row should change a colour from grey to black as on picture below:

Click on "Edit Request Properties Rules" link to hide details panel for the rules. Now click "Save Modifications" to save modifications.

Step 7: posting configuration to the running instances of Flink-ESB Message Gateway

Click on "Gateway Config" tab if not there already, and click "Trigger Instances" button. Confirm a message box by pressing "OK"

Step 8: verifying functionality using browser

Open the browser and type URL https://localhost:8081/service/country/info/DE (or whatever IP and port you have for message gateway). You should get an output as on the picture below:

Go ahead and try other country codes. The output should be exactly the same as the one you received from the SOAP service tested on step 1.