Build an API Integration

Time: Under 10 minutes | What you'll build: An HTTP service that listens on /hello/greeting, calls an external API, and returns the response to the caller.

An HTTP service exposes your integration logic as a REST endpoint. This quick start shows the full cycle: create a service, add a resource, connect to an external API, and test it using the Try-It/Test panel in WSO2 Integrator.

Prerequisites

WSO2 Integrator installed

Visual Designer
Ballerina Code

Step 1: Create the integration

Open WSO2 Integrator.
Select the Create New Integration card.
Set Integration Name to HelloWorldAPI.
Set Project Name to integration-as-api.
Select Create Integration.

Create new integration form with Integration Name set to HelloWorldAPI and Project Name set to integration-as-api

Step 2: Add an HTTP service

Select your integration from the project overview canvas.
Select + Add Artifact in the design canvas.
Select HTTP Service under Integration as API.
Keep Service Contract as Design From Scratch.
Set Service Base Path to /hello.
Select Create.

Selecting HTTP Service in the Add Artifact panel and setting the base path to /hello

Step 3: Add a resource

In the HTTP service design view, select + Add Resource.
Select GET.
Set Resource path to greeting.
Select Save.

Adding a GET resource at the /greeting path in the HTTP service designer

Step 4: Connect to an external API

Select + inside the resource flow.
Select Add Connection.
Select HTTP.
Set Url to https://apis.wso2.com/zvdz/mi-qsg/v1.0.
Set Connection Name to externalApi.
Select Save Connection.

Configuring an HTTP connection to the external API in the Add Connection panel

Step 5: Call the external API

Select + inside the resource flow.
Select externalApi.
Select Get.
Set Path to /.
Set Result to response.
Set Target Type to json.
Select Save.

Configuring the GET call on the externalApi connection with path / and result variable response

Step 6: Return the response

Select + inside the resource flow after the external API call node we just added.
Select Return.
Set Expression to response.
Select Save.

Adding a Return node with the expression set to response

Step 7: Run and test

Select Run.
Select Test in the confirmation dialog.
Select Execute.
Confirm the response shows 200 OK with a Hello World body.

Running the integration and testing it with the Try It panel showing a 200 OK response

The following complete, runnable Ballerina program produces the same integration shown in the visual designer steps.

import ballerina/http;

listener http:Listener httpDefaultListener = http:getDefaultListener();

final http:Client externalApi = check new ("https://apis.wso2.com/zvdz/mi-qsg/v1.0");

service /hello on httpDefaultListener {

    resource function get greeting() returns json|error {
        do {
            json response = check externalApi->get("/");
            return response;
        } on fail error err {
            // handle error
            return error("unhandled error", err);
        }
    }
}

Save this as main.bal, then run bal run from the project directory. Send a request with curl http://localhost:9090/hello/greeting to verify the Hello World response.

What's next

Build an automation — Build a scheduled job
Build an AI agent — Build an intelligent agent
Build an event-driven integration — React to messages from brokers
Build a file-driven integration — Process files from FTP or local directories
HTTP service — Learn resource functions, path parameters, and error handling

Step 1: Create the integration​

Step 2: Add an HTTP service​

Step 3: Add a resource​

Step 4: Connect to an external API​

Step 5: Call the external API​

Step 6: Return the response​

Step 7: Run and test​

What's next​