Build an Integration as API

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

A working WSO2 Integrator environment. Choose the path that fits how you want to work:

• Cloud setup — launch WSO2 Integrator in a browser-based cloud editor.
• Local setup — install and launch the WSO2 Integrator IDE on your machine.

Visual Designer

Step 1: Create the integration

Note

In the cloud editor, you're already inside a project. Skip to Step 2.

1. Open WSO2 Integrator.
2. Select the Create New Integration card.
3. Set Integration Name to HelloWorldAPI.
4. Set Project Name to integration-as-api.
5. Select Create Integration.

Step 2: Add an HTTP service

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

Step 3: Add a resource

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

Step 4: Connect to an external API

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

Step 5: Call the external API

1. Select + inside the resource flow.
2. Select externalApi.
3. Select Get.
4. Set Path to /.
5. Set Result to response.
6. Set Target Type to json.
7. Select Save.

Step 6: Return the response

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

Step 7: Run and test

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

Ballerina Code

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 click the Run button in the top toolbar. Select Test in the confirmation dialog, then select Execute in the Try-It editor. Confirm the response shows 200 OK with a Hello World body.

Step 8: Deploy to WSO2 Cloud

Deploy your integration to WSO2 Cloud - Integration Platform in any of the following ways:

• If you're using the cloud editor, see Save and deploy.

• If you're using the WSO2 Integrator IDE, see Deploy from the IDE.

• If you'd rather skip the build and try a ready-made sample, one-click deploy it:

  

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