Develop an Integration API¶

In this tutorial, you'll learn the basics of setting up and using WSO2 MI to create and deploy an Integration API service with minimal hassle.

What you'll build¶

Let’s try a simple scenario where the client sends a request to the Bank API deployed in the WSO2 Micro Integrator and receives a Welcome to O2 Bank !! greeting response.

What you'll learn¶

How to create an integration project.
How to create an Integration API.
How to deploy and test.

Prerequisites¶

You need Visual Studio Code (VS Code) with the Micro Integrator for VS Code extension installed. The MI for VS Code extension is the official developer tool for designing, developing, and testing integration solutions with WSO2 Micro Integrator.

Info

See the Install Micro Integrator for VS Code documentation to learn how to install Micro Integrator for VS Code.

Follow the instructions below to create your first Integration API.

Step 1 - Create a new integration project¶

To develop the above scenario, let's get started with creating an integration project in the Micro Integrator extension installed VS Code.

Launch VS Code with the Micro Integrator extension installed.
Click on the Micro Integrator icon on the Activity Bar of the VS Code editor.
Click Create New Project on Design View. For more options for creating a new integration project, see Create an Integration Project.
In the Project Creation Form, enter BankIntegration as the Project Name.
Ensure 4.4.0 is selected as the Micro Integrator runtime version.
Provide a location for the integration project under Project Directory.
Click Create.

Once you click Create, the Add Artifact pane will be opened.

Note

You need the following to work with the MI for VS Code extension.

Java Development Kit (JDK) version 21
WSO2 Micro Integrator (MI) 4.4.0 runtime

If you don't have them installed on your local machine, these will be automatically prompted for downloading and configured by the Micro Integrator for VS Code extension during the project creation step:

Click Download Java & MI to download and set up Java and MI runtime.
Info

If a different JDK or WSO2 MI version is installed on your local machine, you'll be prompted to download the required versions.
1. Click Download to install the required JDK or/and MI version(s).
2. Once the download is complete, configure the Java Home or/and MI Home paths by clicking Select Java Home or/and Select MI Path, respectively.
If the required JDK and WSO2 MI versions are already installed, you can directly configure the Java Home and MI Home paths in this step by clicking Select Java Home and Select MI Path, respectively.
Once the process is complete, a window reload will be required, and you will be prompted with the following message:
Click Reload Window.

Step 2 - Create an API¶

Now the integration project is ready to add an API. In this scenario, the API responds to the client with a greeting message. First, let's create an API.

In the Add Artifact interface, under Create an Integration, click on API. This opens the API Form.
Enter BankAPI as the API Name. The API Context field will be automatically populated with the same value.
Click Create.

Once you create the API, a default resource will be automatically generated. You can see this default resource listed in the Service Designer under Available resources. You'll use this resource in this tutorial.

Step 3 - Design the integration¶

Now it's time to design your API. This is the underlying logic that's executed behind the scenes when an API request is made. In this scenario, you need to send back a greeting message to the client. For that, you have to add a Payload mediator. Follow the below steps to add a Payload mediator.

What is a mediator?

Mediators are the core building blocks of message processing in WSO2 Micro Integrator (MI). They define how messages are transformed and routed as they pass through an integration flow. To explore mediators in detail and understand how they work, see the Mediator documentation.

Open the Resource View of the API resource by clicking the GET resource under Available resources on Service Designer.
Once you open the Resource View, click on the + icon on the canvas to open the Mediator Palette.
Under Mediators, select the Payload mediator.
In the Add Payload Mediator pane that appears, provide the following as the payload.
```
{
    "greetings":"Welcome to O2 Bank !!"
}
```
Click Add to add the Payload mediator to the integration flow.

Now let's add a Respond Mediator to respond the message to the client.
Click on the + icon placed just after the Payload mediator to open the Mediator Palette.
Select the Respond mediator from the Mediator Palette, and click Add to add it to the integration flow.

You may refer to the following API configuration for reference,

Bank API

Info

You can view the source view by clicking on the Show Source (</>) icon located in the top right corner of the VS Code.

Design ViewSource View

<?xml version="1.0" encoding="UTF-8"?>
<api context="/bankapi" name="BankAPI" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="GET" uri-template="/">
        <inSequence>
            <payloadFactory media-type="json" template-type="default">
                <format>{
                    "greetings":"Welcome to O2 Bank !!"
                    }
                </format>
            </payloadFactory>
            <respond/>
        </inSequence>
        <faultSequence>
        </faultSequence>
    </resource>
</api>

Step 4 - Run the Integration API¶

Now that you have developed an integration using the Micro Integrator for the Visual Studio Code plugin, it's time to deploy the integration to the Micro Integrator server runtime.

Click the Build and Run icon located in the top right corner of VS Code.

Step 5 - Test the Integration API¶

Now, let's test the Integration API. For that, you can use the inbuilt try-it functionality in the MI for VS Code extension.

When you run the integration as in Step 4, the Runtime Services interface is opened up. You can see all the available services.

Select BankAPI that you have developed and test the resource.

Congratulations! Now, you have created your first Integration API.

What's Next?¶

So far, you have responded to the client with a mock payload. Next, you will explore how to route and transform the payload effectively.

Click on the Next button below to continue to the next tutorial.

Next →