Build an Integration as API

TimeUnder 10 minutes

What you'll buildAn 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.

WSO2 Cloud setupSign up and launch WSO2 Integrator in the browser-based cloud editor.

Step 1: Create the integration

On the project home page, click Create on Cloud.
The WSO2 Integrator cloud editor opens in your browser. Add an artifact to your integration, then deploy it to WSO2 Cloud from the Deploy to WSO2 Cloud panel on the right.

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

Step 8: Deploy to WSO2 Cloud

Deploy your integration to WSO2 Cloud. Check Save and deploy.

Skip ahead: deploy a ready-made sample

Rather not build it yourself? One-click deploy the HelloWorldAPI sample straight to WSO2 Cloud.

Source code

View the generated Ballerina code

The steps above generate the following complete, runnable Ballerina program:

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);
        }
    }
}

Prerequisites​

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​

Step 8: Deploy to WSO2 Cloud​