Quick Start Guide¶
In this guide, you'll build a simple integration using the Ballerina Integrator plugin. You'll create an HTTP service with a single resource named greeting
that invokes the public Hello World API endpoint and returns the response.
Step 1: Install Visual Studio Code¶
Download and install Visual Studio Code.
Step 2: Install the WSO2 Ballerina Integrator extension¶
- Go to the Extensions view by clicking the extension icon on the sidebar or pressing
Ctrl + Shift + X
on Windows and Linux, orShift + ⌘ + X
on a Mac. - Search for
Ballerina Integrator
in the extensions view search box. -
Click on the Install button to install the
Ballerina Integrator
extension. -
This will install the Ballerina Integrator and Ballerina extensions on VS Code.
Step 3: Set up Ballerina Integrator for the first time¶
-
Click on the Ballerina Integrator icon on the sidebar.
-
Click on the Set up Ballerina distribution button.
- The setup wizard will install and configure the Ballerina distribution required for Ballerina Integrator.
-
Click on the Restart Now button to complete the setup.
Step 4: Create a new integration project¶
- Click on the Ballerina Integrator icon on the sidebar.
- Click on the Create New Integration button.
- Enter the Integration Name as
HelloWorld
. - Select the project directory by clicking on the Select Path button.
-
Click on the Create Integration button to create the integration project.
Step 5: Create an integration service¶
Generate with AI
The integration service can also be generated using the AI-assistant. Click on the Generate with AI button and enter the following prompt, then press Add to Integration to generate the integration service.
Create an http service that has base path as /hello, and 9090 as the port. Add GET resource on /greeting that invokes https://apis.wso2.com/zvdz/mi-qsg/v1.0 endpoint and forward the response to the caller.
- In the design view, click on the Add Artifact button.
- Select HTTP Service under the Integration as API category.
- Select the Create and use the default HTTP listener option from the Listeners dropdown.
- Select the Design From Scratch option as the Service Contract.
- Specify the Service base path as
/hello
. -
Click on the Create button to create the new service with the specified configurations.
Step 6: Design the integration¶
- The generated service will have a default resource named
greeting
with theGET
method. - Click on the
greeting
resource to view the resource details. Let's modify the resource to invoke theHelloWorld
API endpoint. - Hover over the arrow after start and click the ➕ button to add a new action to the resource.
- Select Add Connection from the node panel.
- Search for
HTTP
in the search bar and select HTTP as the connection type. - Change the Connection Name to
externalEP
. -
Add the URL
"https://apis.wso2.com"
to the connection URL field and click Save. -
Click the ➕ button again and select Connections -> externalEP -> get from the node panel.
-
Fill in the request details as below and click Save.
Field Value Variable Name epResponse
Variable Type string
Connection externalEp
Target Type string
Path "/zvdz/mi-qsg/v1.0"
-
Click ➕ button again and select Return from the node panel.
-
Select the
epResponse
variable as the Expression from the dropdown and click Save. This step will return the response from theHelloWorld
API endpoint.
Step 7: Run the integration¶
- Click on the Run button in top right corner to run the integration.
- The integration will be compiled and started in the embedded Ballerina runtime.
- Once the integration is started, click on the Test button to open the embedded HTTP client.
-
Click on the Send button to invoke the
greeting
resource. -
Additionally, you can test the integration using REST clients like Postman or curl.
curl http://localhost:9090/hello/greeting {"message":"Hello World!!!"}%
-
Click on the ⏹️ button or press
Shift + F5
shortcut to stop the integration.