A Match Made in Heaven for API-Based Integration

WSO2 Enterprise Integrator + WSO2 API Manager

The integration world consists of many “wonders”. When deciding what to choose for API-based integration, there is pair that you can choose which will lead to solid solutions. The perfect pair for your integration solution would be the WSO2 Enterprise Integrator and the WSO2 API Manager to serve you with their magic.

“Some things are forever”

This article will use the WSO2’s Enterprise Integrator and API Manager collaboratively to implement a simple integration solution, thus proving these two are a match made in heaven that will remain forever.

In simple words,

I will show you the way to implement a GitHub Alerting Solution using the WSO2 Enterprise Integrator and the WSO2 API Manager, that can send notifications to a Google Chat room stating the number of issues (open or closed) in a particular GitHub repository.

Snapshot of Magic

Before diving into the deep, let me explain the use case and the design of the solution that I will be discussing shortly.

The above diagram depicts the basic design flow of this solution. WSO2 Micro Integrator deploys the CApp (Carbon Application) named GitHubAlertsAPI which has a resource created using GitHub REST API and the Google Hangouts Chat API.

WSO2 API Manager will use this API (CApp) as the backend endpoint for its API named GitHubAPI that will contain a resource that is mapped to the resource of CApp.

This article will show you the way to implement this scenario and how you can invoke this API.

First things First

This article will tell you how to create a simple API and deploy it. But this can be enhanced with more complicated logic and designs if you understand the basics. Therefore, I insist you try this with me.

• Download and setup WSO2 Integration Studio 7.2.0 (You can download the distribution from here).
• Download and setup WSO2 Enterprise Integrator 7.1.0 (You can download the distribution from here).
• Download and setup WSO2 API Manager 3.2.0 (You can download the distribution from here).

Let me show you the magic with four (4) steps. Are you ready?

1. Configure a Google Chat room Webhook
2. Create the CApp using WSO2 Integration Studio
3. Managing your API with WSO2 API Manager
4. Enhance your API Management

Let the magic begin

Step 1 — Configure a Google Chat room Webhook

Since this solution will send messages to Google Chat rooms it is a must to configure a Google Chat room Webhook prior to implementing/using the application. You can follow the below steps for this.

1. Go to your Google Account and create a Chat room.

2. Go to the created room and click on the drop-down near its name.

3. Click on Manage Webhooks and the below window will appear. Give a name (and a URL to a photo if you like) and Save.

4. Copy the URL that you got which will be displayed in the below window and save it in a text file for future use. (You should get a URL that is similar to https://chat.googleapis.com/v1/spaces/XXXXXXXXXXX/messages?key=<with a key value>)

Step 2— Create the CApp using WSO2 Integration Studio

1. Create a new project

• Open WSO2 Integration Studio 7.2.0 and click New Integration Project in the Getting Started view.
• Specify the Integration Project Name as GitHubAlerts (Make sure to leave the Create ESB Configs and Create Composite Exporter checkboxes selected as shown below) and click on Finish.

2. Create Endpoints Artifacts

• Right-click GitHubAlertsConfigs and go to New → Endpoint to open the New Endpoint Artifact dialog box.

Go to GitHubAlertsConfigs → New → Endpoint to open the New Endpoint Artifact

• Create an Endpoint named GitHubSearchEndpoint.xml by clicking the New Endpoint Artifact dialog box that opens, select Create a New Endpoint and click Next. Enter the details as shown below.

Endpoint Name: The name of the endpoint (Eg: GitHubSearchEndpoint )

Endpoint Type: The type of the endpoint (Eg: HTTP Endpoint )

URI Template: The URL that should be invoked when calling the endpoint. (Eg: https://api.github.com/search/issues?q=repo:{uri.var.owner}/{uri.var.repo}+type:issue+state:{uri.var.state} This endpoint takes 3 values such as owner name, repository name and the state in order to query the issues in a particular GitHub repo that belongs to a particular owner. For example, you can use, https://api.github.com/search/issues?q=repo:wso2/product-apim+type:issue+state:open to get the open issues which are in the https://github.com/wso2/product-apim repo)

Method: Request type (Eg: GET )

• Similarly, create another Endpoint named ChatAlertEndpoint.xml. Make sure to use the webhook URL that you saved in Step 1 — (4) as the URI Template for this endpoint and set the Method as POST .

3. Create the REST API

• Right-click GitHubAlertsConfigs in the project explorer and go to New → REST API to open the API Artifact Creation Options dialog box.

• Select Create A New API Artifact and click Next.
• Specify values for the required REST API properties as shown below and click Finish. The REST API will be created in the src/main/synapse-config/api folder under GitHubAlertsConfigs .

4. Create the API resources

To access the REST API, the API should contain resources. In this step, I will be creating one resource that can be called to “retrieve the number of open issues in a GitHub repository and send an alert to the Google Chat room”. (Note that, you can implement any number of resources to cater to your needs in your API as you wish)

• Open the newly created REST API artifact GitHubAlertsAPI from the project explorer. You will see the graphical view of the GitHubAlertsAPI with its default API Resource as shown below.

• Double-click the API resource to open the Properties view and enter the values for Url Style, Uri Template and Methods as shown below.

5. Create the mediation logic

This is the place where you define your logic for the integration task. You can use any set of mediators in the official documentation for this task according to your need and choice. Follow the below steps to create the logic for the GitHubAlerts API.

• Drag and drop a Property mediator from the mediator palette into the Resource as shown below.

• Define the properties of the Property mediator as below and save it. (Set the New Property Name as issueState and make sure to set the Property Data Type to STRING . Under the Value section set the Value as expression: $ctx:uri.var.state . The purpose of this is to save the issue state passed when calling the API resource, in a property named issueState so that it can be accessed later within a mediator named Script mediator. Refer here to learn more about the Property mediator)

• Drag and drop a Call mediator from the mediator palette next to the Property mediator shown below.

• Now, drag the already-defined GitHubSearchEndpoint artifact, which is available under the Defined EndPoints section of the palette, into the Call mediator as shown below.

Note:- Recall the step that we created this endpoint. We have set the URL Template of the endpoint as https://api.github.com/search/issues?q=repo:{uri.var.owner}/{uri.var.repo}+type:issue+state:{uri.var.state}. Here the values, uri.var.owner, uri.var.repo and uri.var.state will be taken from the passed parameters when calling the API resource which we designed from its URI-Template /issuesAlert/{owner}/{repo}/{state}. This will get more clarified when we invoke the API resource in the upcoming steps.

• Next, drag and drop a Script mediator next to the GitHubSearchEndpoint as shown below. This mediator will contain the logic to process the payload from the call to GitHubSearchEndpoint.

• Let’s change the properties of the Script mediator according to our needs. Select the Script Language as jsand select the Script Type as INLINE for simplicity (Note that you can use the REGISTRY_REFERENCE type as well, but I have used INLINE to simplify this more. Refer here to learn more about the Script mediator). In the Script Body, enter the following code segment.

var payload = mc.getPayloadJSON();
var messageAlert = "The total " + mc.getProperty("issueState") + " issue count is " + payload.total_count;
mc.setProperty("messageText", messageAlert.toString());

Confused?

You did not get what I did before with the Script mediator, right? Do not worry, let me explain.

• I have used a JS (JavaScript) script inside the Script mediator to process the payload from the endpoint call. The call to the endpoint URL: https://api.github.com/search/issues?q=repo:{uri.var.owner}/{uri.var.repo}+type:issue+state:{uri.var.state} will return you a payload and it can be accessed using mc.getPayloadJSON().
• Then I have constructed the message (referred to as messageAlert)to be sent to the Google Chat room. When constructing the message, I have retrieved the issueState property (which I stored using a property mediator in a previous step). Furthermore, I have taken the issue count (which is stored in a field named total_countinside the payload from the endpoint) using payload.total_count .
• Finally, I have set the message in a property named messageText that can be used later when sending the alert to the Google Chat room.

Easy right? I think you have everything under control now.

• Next, add a PayloadFactory mediator next to the Script mediator as shown below.

• Specify values for the required PayloadFactory properties as below.

Payload Format: Inline

Media Type: json

Payload: {"text":"$1"}

• Now, click on the + sign in the Args and select the Argument Type as Expression in the PayloadFactoryArgument dialog box.

• When you click on the Argument Expression another dialog box will appear as shown below. Enter get-property('messageText') and click OK.

• Now the PayloadFactoryArgument dialog box will look like below. Click Finish.

• Finally, the PayloadFactory mediator properties will look like below.

Confused again?

Confused again? Let me explain what I did.

• The PayloadFactory mediator can be used when you want to prepare a message payload that can be send using a POST request. To send the message to the Google Chat room using the ChatAlertEndpoint, you need to have a JSON payload that consists of the property “text” with the message to be sent. (You can refer here to learn more about the PayloadFactory mediator)
• This is the reason why I have defined the Payload as {"text":"$1"} . Using $1 we can assign a dynamic value to “text”. That dynamic value will property which we set previously as messageText .
• As a summary, what we do here is, create a JSON payload with an attribute named “text” with the value of the property messageText in order to send it to the ChatAlertEndpoint.

I hope it is clear now?

• As the final step under the topic 5. Create the mediation logic, add a Call mediator, ChatAlertEndpoint and a Respond mediator as shown below (Respond mediator will send the response back to the client after retrieving from the endpoint. To learn more about this refer here). This would be the final picture of the CApp that we created using the WSO2 Integration Studio.

The final picture of the CApp to send GitHub issue alerts to Google Chat rooms

Tip:- You can check the final source view of the GitHubAlertsAPI. It will look like below.

payload.total_count

6. Build and run the artifacts

There are two (2) ways to run the artifacts as mentioned here. I will be using Option 2: Using a local Micro Integrator instance. After downloading and setup the WSO2 Enterprise Integrator 7.1.0 as mentioned in the First things First section, follow the steps given below. (The home directory of your Enterprise Integrator installation will be referred to as <EI_HOME> from hereon)

• Export the artifacts as a deployable CAR file: Right-click GitHubAlertsCompositeExporter in WSO2 Integration Studio and select Export Composite Application Project.

• Deploy the GitHubAlerts service: Copy the exported CAR file of the GitHubAlerts service to the <EI_HOME>/micro-integrator/repository/deployment/server/carbonapps directory.
• Start the Micro Integrator (Refer here to learn how to start Micro Integrator server). By default, the HTTP listener port is 8290 and the default HTTPS listener port is 8253.
• Now using the below cURL we can test whether our CApp works as expected.

curl http://localhost:8290/githubalerts/issuesAlert/wso2/product-apim/open

The above cURL command uses the REST API which we created and uses its resource named issuesAlert . The passed parameters are, owner = wso2, repo = product-apim and the state = open . The above cURL will show you a response like below in the terminal.

Meanwhile, your Google Chat room might have received a message similar to the below alert.

Here comes the role of WSO2 API Manager!

Here comes WSO2 API Manager into the play

Step 3— Managing your API with WSO2 API Manager

The role of the WSO2 API Manager enhances the magic of WSO2 Enterprise Integrator, by providing not only API designing but also provides the facilities for API publishing, lifecycle management, application development, API security, rate limiting, viewing statistics of APIs, as well as connecting APIs, API Products, and endpoints, thus leading to a complete set of integration abilities.

1. Create an API using the Publisher Portal

• Start the WSO2 API Manager 3.2.0 by navigating to <AM_HOME>/bin. (Refer here for more information on starting the server. The home directory of your API Manager installation will be referred to as <AM_HOME> from hereon)
• Sign in to the Publisher Portal as the admin user (username: admin, password: admin) https://<hostname>:9443/publisher . Then, click on Create New API and choose Design a New REST API. (Refer here to learn more about creating a REST API)

• Enter the details as shown below and click on Create.

• Remove the existing resources and add a new GET resource as issuesAlert/{owner}/{repo}/{state} (If you recall the past, you may remember that this is similar to the resource that we created in CApp using the WSO2 Integration Studio). Now click Save.

• Go to the Lifecycle tab of the API and click Publish to publish the API to the gateway so that the consumers can access it from the Developer Portal.

2. Subscribe to the API

• Sign in to the Developer Portal as the admin user (username: admin, password: admin) https://<hostname>:9443/devportal . You can see the GitHubAPI is published and is visible to the Developer Portal.

• Click on the API and navigate to Subscriptions tab.

• Click on SUBSCRIBE button under the application named DefaultApplication. Now you have been successfully subscribed. (To learn more about subscribing to an API refer here)

3. Generate Keys and Invoke the API

• Let’s navigate to the Applications tab (on top) and select the DefaultApplication, since you subscribed using it.
• Go to the Production Keys tab and click GENERATE KEYS.

• Copy the Access Token that was generated.

• Navigate to the GitHubAPI again and click on Try Out tab. Paste the Access Token in the cell named access token.

• Expand the GET reource, click on Try it out and enter the values as shown below.

• Now click on Execute and let the magic begin. You will receive a response as below in the UI.

• Meanwhile, you may receive an alert in your Google Chat room that is similar to the below alert.

Tip:- Try several owner, repo and state combinations and generate alerts. Below is another example when you pass owner = wso2 , repo = product-apim and state = closed .

Step 4 — Enhance your API Management

In the above step, we generated an Access Token and invoked the API. This enforces authentication for an API which is a security concern. You can try out various API Management related tasks such as lifecycle management, rate limiting, endpoint security, documentation management, API analytics using the WSO2 API Manager. (Refer here for official documentation)

Furthermore, you can access this managed API using applications such as Android Apps, Node Apps, Web Apps, etc.

Wrap things Up!

In this article, we have seen how four (4) WSO2 can be consolidated in a powerful manner when finding solutions for API-based integration. We used WSO2 Integration Studio to implement the logic of the CApp, by integrating two (2) endpoints which are GitHub REST API and Google Hangouts Chat API. Then we deployed the CApp in the WSO2 Micro Integrator which is a sub-product of WSO2 Enterprise Integrator. Finally, we used WSO2 API Manager to do the API Management tasks such as authentication (Access using tokens).

More enhanced and improved stuff can be done using these four (4) products. This confirms that the WSO2 product family is forever.

Stay tuned for upcoming articles for wondrous achievements that can be accomplished using these products.

Goodbye until the next time…

References

WSO2 API Manager Documentation 3.2.0

WSO2 Enterprise Integrator Documentation