How to train your Micro Integrator?
WSO2 Micro Integrator is an open source Integration runtime of Enterprise Integrator which is used for integrating APIs, services, data, and SaaS, proprietary, and legacy systems. It is an ESB which went on to evolve as an Integration platform which serves both monolithic and microservices architecture. It is an ideal platform for a developer to develop an Integration solution without learning any Programming language. In this blog, I am going to implement a simple Integration scenario with Micro Integrator which explains the basic functionality and the syntax. This blog is fairly useful if you are a newbie to WSO2 Micro Integrator. You can implement almost all the Enterprise Integration patterns with the Micro Integrator. All the Integration logic is written with XML like syntax.
Basic components
To write an Integration logic in Micro Integrator (MI), one must be familiar with the following terms.
Mediator
A mediator is the basic message processing unit and a fundamental part of the Integration logic. It performs a predefined action on a given message.
Sequence
A sequence is a list of mediators, that means it can hold other mediators and execute them. When a message is delivered to a sequence, it sends the message through all its child mediators sequentially.
Proxy
A Proxy service is a way of triggering a mediation flow. A proxy service can also switch transports, transform a message via a mediation sequence and provide QoS. It can handle different transports like HTTP, JMS, VFS etc and retrieve the message to perform mediation on it.
API
A REST API is made of one or more Resources, which are logical components of an API that can be accessed by making a particular type of HTTP call.
Endpoint
An endpoint defines an external destination for a message/request. An endpoint could represent a URL, a JMS queue, a TCP socket, etc. along with the settings needed for the connection.
With the above knowledge gathered, we can start implementing a simple Integration scenario. For a sample backend service, I am going to use the Weather API provided by OpenWeather organization. A simple use case of this API is to retrieve the weather information of a particular city. For example, a simple CURL request to the following API http://api.openweathermap.org/data/2.5/weather?q=London&appid=<APP_ID> would retrieve the following information.
With Micro Integrator, I am going to demonstrate a simple Integration logic. I’ll be sending names of two cities in an array and retrieve information for both cities in a single response
To try out this sample, you need to sign up at OpenWeather and get an APP ID. https://openweathermap.org/appid#get
Before diving into the Integration logic, I am going to explain the mediators (message processing units) that I am going to use.
Property Mediator
A property mediator is similar to a variable in a programming language. We can read a particular content of the message payload and we can store it in a property for further use. The property will be stored in the Message context which contains all the headers, payload and any other information that is needed for the mediation. Message context will be passed from one mediator to another throughout the mediation. I will be using this mediator to store our APP_ID for Weather API. (Use your own OpenWeather APP_ID in the value field)
<property name="uri.var.appid" scope="default" type="STRING" value=""/>Send Mediator
Send mediator is used to send messages out of Micro Integrator via Endpoints. The endpoint can be defined inside the Send mediator or you can define it separately and use the endpoint key here.
<send>
<endpoint>
<http method="get" uri-template="<Weather_API_URL>"/>
</endpoint>
</send>Iterate Mediator
The Iterate Mediator implements the Splitter enterprise integration pattern and splits the message into a number of different messages derived from the parent message. Since we are going to accumulate weather details for more than one city, we can use this mediator to derive the individual request for each city.
<iterate expression=”json-eval($.cities)” id=”cities”>Aggregate Mediator
The Aggregate mediator implements the Aggregator enterprise integration pattern. It combines (aggregates) the response messages of messages that were split by the Iterate mediator. Under onComplete, we can decide on what should happen to the aggregated message. Here I have simply sent back the response to the client using send mediator. Also note that, I have used the same id for Iterate and Aggregate mediator. It ensures that all the messages that were split in the Iterate mediator will be aggregated in Aggregate mediator. We do not have to define the number of iterations in the payload.
<aggregate id="cities">
<completeCondition>
<messageCount max="-1" min="-1"/>
</completeCondition>
<onComplete expression="json-eval($)">
<send/>
</onComplete>
</aggregate>To organize the mediators, we have two basic sequences : InSequence and OutSequence. Before sending the request to the backend service, we process the message in InSequence. OutSequence is used to process the response that is sent from the backend service. (There are certain exceptions to this statement). The diagram below depicts what I just explained here.
With the basics explained, I have written the complete Integration logic below. I have defined one POST resource inside the API with the context ‘/weather’. It will Iterate over the cities list and send a GET request to WeatherAPI and aggregate the result.
Let’s try out this in Micro Integrator. I’ll be using Micro Integrator 1.2.0 which comes under WSO2 Enterprise Integrator 7.1.0 umbrella.
To download Micro Integrator, you can either visit https://wso2.com/integration/ or https://wso2.com/integration/micro-integrator/ and download the Zip Archive. Inside the zip, you will find the micro-integrator folder which contains the runtime. I will be referring to this folder as MI-HOME from here onwards.
Create an XML file called WeatherByCityAPI.xml in the following location and copy the above API configuration into it. (You may have to create a folder called api inside the default folder if you are using a freshly downloaded MI)
<MI-HOME>/repository/deployment/server/synapse-configs/default/apiAfter creating the file, open your terminal and run the following command inside <MI-HOME>. (If you are on a Windows environment, run the .bat file.)
sh /bin/micro-integrator.shThis will start the MI instance and your API will be deployed. Use the following curl command to send a request to your Micro Integrator instance.
curl --location --request POST 'http://localhost:8290/weather' \
--header 'Content-Type: application/json' \
--data-raw '{"cities": [{"name": "London"},{"name": "Sydney"}]}'Voila… Below is the combined response that you would get.
You sent only one request, but the Integration logic converted it into two messages and sent two requests to the backend service and accumulated back the response and sent it back to you.
Do not stop there. You can send any number of cities in the request and get the response.
This Integration logic I implemented is very straightforward and simple. A developer might be having a complex Integration scenario and writing XML files for complex scenarios is not very developer friendly. WSO2 Integration studio is a graphical development environment which helps a developer to design, develop, debug and test the Integration solutions flawlessly. WSO2 Micro Integrator and WSO2 Integration studio together creates a powerful Integration framework and Low-Code development environment to develop complex Integration scenarios.
References
