Skip to main content

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.

Step 1: Create the integration​

  1. On the project home page, click Create on Cloud.

    WSO2 Cloud project home showing the Create on Cloud optionWSO2 Cloud project home showing the Create on Cloud option
  2. The WSO2 Integrator cloud editor opens in your browser.

    WSO2 Integrator cloud editor landing page showing an empty integration and the Deploy to WSO2 Cloud panelWSO2 Integrator cloud editor landing page showing an empty integration and the Deploy to WSO2 Cloud panel
Note

The cloud editor creates a default integration for you, so you don't need to name it now. You can change its name when you deploy it. For more information, see Save and deploy.

Step 2: Add an HTTP service​

  1. 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
  2. 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
  3. Keep Service Contract as Design From Scratch.

  4. Set Service Base Path to /hello.

  5. 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 highlighted under ConnectionsNode panel with Add Connection highlighted under Connections
  3. Select HTTP under Pre-built Connectors.

    Add Connection dialog with the HTTP connector highlighted under Pre-built ConnectorsAdd Connection dialog with the HTTP connector highlighted under Pre-built Connectors
  4. The Connect to Third-Party service form opens. Set Url to:

    https://apis.wso2.com/zvdz/mi-qsg/v1.0
    Connect to Third-Party service form with Url setConnect to Third-Party service form with Url set
  5. Scroll to the bottom of the form. Set Connection Name to externalApi.

  6. Click Save Connection.

    Connect to Third-Party service form with Connection Name set to externalApiConnect to Third-Party service 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, below the external API call node you 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.

  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​

To deploy your integration to WSO2 Cloud from the cloud editor, see 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.

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