Skip to main content
Version: 5.1

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.

Local setup

Install and launch WSO2 Integrator on your machine.

WSO2 Cloud Account

For AI assisted development and WSO2 Cloud deployments.

Step 1: Create the integration​

Note

If you're using the cloud editor, a project is already open, so you can skip this step and go directly to Step 2: Add an HTTP service.

  1. Open WSO2 Integrator.

  2. Click Create in the Create a Project card.

    WSO2 Integrator home screen with the Create a Project cardWSO2 Integrator home screen with the Create a Project card

  3. Set Project Name to integration-as-api.

  4. Set Integration Name to HelloWorldAPI.

  5. Click Create.

    Create a Project form with Project name set to integration-as-api and Integration name set to HelloWorldAPICreate a Project form with Project name set to integration-as-api and Integration name set to HelloWorldAPI

Step 2: Add an HTTP service​

  1. Select your integration from the project overview canvas.

  2. In the design view, click Add Artifact Manually.

    Integration design view with the Add Artifact manually button highlightedIntegration design view with the Add Artifact manually button highlighted

  3. Select HTTP Service under Integration as API.

    Artifacts page with HTTP Service highlighted under Integration as APIArtifacts page with HTTP Service highlighted under Integration as API

  4. Keep Service Contract as Design From Scratch.

  5. Set Service Base Path to /hello.

  6. Click Create.

    Create HTTP Service form with Service Base Path set to /helloCreate HTTP Service form with Service Base Path set to /hello

Step 3: Add a resource​

  1. In the HTTP service design view, click + Add Resource.

  2. Select GET.

    Select HTTP Method to Add panel with GET highlightedSelect HTTP Method to Add panel with GET highlighted

  3. Set Resource path to greeting.

  4. Click Save.

    New Resource Configuration panel with Resource Path set to greetingNew Resource Configuration panel with Resource Path set to greeting

Step 4: Connect to an external API​

  1. Click + inside the resource flow.

    Resource flow with the add node button highlightedResource flow with the add node button highlighted

  2. Click Add Connection under Connections.

    Node panel with Add Connection highlightedNode panel with Add Connection highlighted

  3. Select HTTP under Pre-built Connectors.

    Add Connection dialog with the HTTP connector highlightedAdd Connection dialog with the HTTP connector highlighted

  4. The Configure HTTP form opens. Set Url to:

    https://apis.wso2.com/zvdz/mi-qsg/v1.0
    Configure HTTP form with Url setConfigure HTTP form with Url set

  5. Scroll to the bottom of the form. Set Connection Name to externalApi.

  6. Click Save Connection.

    Configure HTTP form with Connection Name set to externalApiConfigure HTTP form with Connection Name set to externalApi

Step 5: Call the external API​

  1. Click + inside the resource flow.

    Resource flow with the add node button highlightedResource flow with the add node button highlighted

  2. Select externalApi.

  3. Select Get.

    Node panel with the externalApi connection and its Get action highlightedNode panel with the externalApi connection and its Get action highlighted

  4. Set Path to /.

  5. Set Result to response.

  6. Set Target Type to json.

  7. Click Save.

    externalApi get form with Path, Result, and Target Type setexternalApi get form with Path, Result, and Target Type set

Step 6: Return the response​

  1. Click + inside the resource flow after the external API call node we just added.

    Resource flow with the add node button highlighted after the http:get nodeResource flow with the add node button highlighted after the http:get node

  2. Select Return under Control.

    Node panel with Return highlighted under ControlNode panel with Return highlighted under Control

  3. In the Expression field, select response from the variables.

  4. Click Save.

    Return panel with Expression set to responseReturn panel with Expression set to response

Step 7: Run and test​

  1. Click Run.

  2. Click Test in the confirmation dialog.

  3. Click Execute Cell.

  4. 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 responseRunning 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 - Integration Platform in any of the following ways:

Skip ahead: deploy a ready-made sample

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

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

What's next​

Last updated on
On this page
Was this page helpful?
Report an issue