Connecting Web APIs/Cloud Services¶

What you'll build¶

When you integrate the systems in your organization, it is also necessary to integrate with third-party systems and their capabilities to enhance your services. WSO2 Micro Integrator uses Connectors for the purpose of referring the APIs of third-party systems.

In this tutorial, when a client sends an appointment reservation request to the Micro Integrator, the client should receive an email confirming the appointment reservation details. To build this use case, you can add an Email connector to the mediation flow.

Let's get started!¶

Step 1: Set up the workspace¶

The following software and configurations are required to proceed with this tutorial:

Visual Studio Code (VS Code): with the Micro Integrator extension installed.
Java Development Kit (JDK): Version 11 or 17 is required. Ensure the JDK is properly configured in your system's PATH environment variable.
Apache Maven: Ensure Apache Maven is installed and its path is correctly set within the system's PATH environment variable.

Info

Follow the Install Micro Integrator for VS Code documentation for a complete installation guide.

Step 2: Develop the integration artifacts¶

Create an integration project¶

The Integration project will contain all the required artifacts for the integration solution.

Launch VS Code with the Micro Integrator extension installed.
Click on the Micro Integrator icon on the Activity Bar of the VS Code editor.
Click Create New Project on Design View.

Next, the Project Creation Form will be opened.
In the Project Creation Form, enter SampleServices as the Project Name.
Provide a location under Select Project Directory.
Click Create.

Now let's start designing the integration by adding the necessary artifacts.

Create an endpoint¶

An Endpoint artifact is required to expose the URL that connects to the back-end service.

Navigate to the MI Project Explorer > Endpoints.
Hover over Endpoints and click the + icon that appears.
Next, select HTTP Endpoint type from the Create Endpoint Artifact interface.

In the HTTP Endpoint Form that appears, specify the following values to create the new endpoint.

Property	Value	Description
Endpoint Name	`HospitalServicesEP`	This is a single endpoint configured to forward requests to the relevant hospital by reading the hospital specified in the request payload.
URI Template	`http://localhost:9090/{uri.var.hospital}/categories/{uri.var.category}/reserve`	The template for the request URL is expected by the back-end service. The following two variables will be replaced by the corresponding values in the request message: {uri.var.hospital} {uri.var.category}
Method	`POST`	Endpoint HTTP REST Method.

Create an email connection¶

Navigate to the MI Project Explorer > Connections. Hover over Connections and click the + icon that appears.
Next, select the Email connector from the appeared connector menu.

In the Add New Connection form that appears, specify the following values to create the new endpoint.

Tip

If you have enabled 2-factor authentication, an app password should be obtained as instructed here.

Property	Description
Connection Name	Enter `smtpsconnection`
Connection Type	Select `SMTPS` for SMTP Secured Connection.
Host	Enter `smtp.gmail.com`
Port	Enter `465`
Username	Enter your email address
Password	Enter your email password
Require TLS	Select `false`

Create the REST API¶

Go to MI Project Explorer > APIs.
Hover over APIs and click the + icon that appears to open the API Form.

Specify values for the required REST API properties:

Property	Value	Description
Name	`HealthcareAPI`	The name of the REST API.
Context	`/healthcare`	Here you are anchoring the API in the `/healthcare` context. This will become part of the name of the generated URL used by the client when sending requests to the Healthcare service. For example, setting the context to `/healthcare` means that the API will only handle HTTP requests where the URL path starts with `http://host:port/healthcare.`

Click Create. This will open the Service Designer interface.

You can now start configuring the API resource.
Click on the GET API resource under Available resources on the Service Designer.

You will now see the graphical view of the HealthcareAPI with its default API Resource.
Click the Edit icon to edit the API resource.

Specify values for the required resource properties:

Property	Description
URI Template	`/categories/{category}/reserve` This defines the request URL format. In this case, the full request URL format is `http://host:port/categories/{category}/reserve` where `{category}` is a variable.
URL Style	`URI_TEMPLATE`
Methods	`POST` This defines that the API resource only handles requests where the HTTP method is POST.

Click Update.

Update the mediation flow¶

You can now start updating the API resource with the mediation flow.

Navigate to the MI Project Explorer > APIs > HealthcareAPI > /categories/{category}/reserve.
To add Property mediator click + icon in the design view and select Property mediator from the palette. This is used to extract the hospital name that is sent in the request payload.

With the Property mediator selected, access the Property tab and specify the details given below.

Property	Value	Description
Property Name	`uri.var.hospital`	The name that will be used to refer to this property's values.
Property Action	`set`	The property action.
Property Data Type	STRING	The data type of the property.
Property Scope	`default`	The scope of the property.
Value (Expression)	`json-eval($.hospital_id)`	Click the Ex button in the Value field towards the end. This specifies the value type as an expression. Enter `json-eval($.hospital_id)` as the expression value. Note: This is the JSONPath expression that will extract the hospital from the request payload.
Description	Get hospital name

Click Submit.
Add another Property Mediator by clicking + after the previously added property mediator and selecting Property Mediator from the palette. This is used to extract the patient's email address.

With the Property mediator selected, access the Property tab and specify the details given below.

Property	Description
Property Name	Enter `email_id`.
Property Action	Enter `set`.
Property Data Type	STRING
Property Scope	Enter `default`
Value	Click the Ex button in the Value field towards the end. This specifies the value type as expression. Enter `json-eval($.patient.email)` to overwrite the default expression.
Description	Get Email ID

Add a Call Mediator by clicking + after the added property mediators and selecting Call Mediator from the palette. Then select the HospitalServicesEP endpoint from the endpoint drop-down and click Submit.

Info

Using the Call mediator allows us to define other service invocations following this mediator.

Note

The following response will be returned from GrandOakEP, ClemencyEP, or PineValleyEP:

{"appointmentNumber":1,   "doctor":
    {"name":"thomas collins",
             "hospital":"grand oak community hospital",
             "category":"surgery","availability":"9.00 a.m - 11.00 a.m",
             "fee":7000.0},
       "patient":
           {"name":"John Doe",
            "dob":"1990-03-19",
            "ssn":"234-23-525",
            "address":"California",
            "phone":"8770586755",
            "email":"[email protected]"},
       "fee":7000.0,
       "confirmed":false}

Add another Property mediator just after the call mediator to retrieve and store the response sent from HospitalServiceEP. This will be used within the body of the email.

With the Property mediator selected, access the Property tab and specify the details given below.

Property	Description
Property Name	Enter `hospital_response`.
Property Action	Enter `set`.
Property Data Type	STRING
Property Scope	Enter `default`
Value	Click the Ex button in the Value field towards the end. This specifies the value type as expression. Enter `json-eval($)` to overwrite the default expression.
Description	Get Hospital Response

Click + icon below the previously added property mediator and add the Send operation from the Email Connector palette.
With the Send operation selected, access the property tab, and select the created connection as Connection from the drop-down in the properties window.

Specify the following details in the property tab;

Property	Description
From	Enter your email address as the value. This will be the account from which the email is sent.
To	Click the Ex button in the Value field towards the end. This specifies the value type as expression. Enter `$ctx:email_id` as the value. This retrieves the patient's email address that was stored in the relevant Property mediator.
Subject	Enter `Appointment Status` as the value. This is the subject line in the email that is sent out.
Content	Click the Ex button in the Value field towards the end. This specifies the value type as expression. Enter `$ctx:hospital_response` as the value. This retrieves the payment response that was stored in the relevant Property mediator.

Add a Respond mediator to end the sequence processing.

We have now finished creating all the required artifacts.

Step 3: Build and run the artifacts¶

Prerequisites

Before you begin, install Micro Integrator on your machine:

Go to the WSO2 Micro Integrator web page, click Download, provide necessary details, and then click Zip Archive to download the Micro Integrator distribution as a ZIP file.
Extract the ZIP file. The extracted folder will be referred as the <MI_HOME> folder.

Once you have downloaded and set up the Micro Integrator locally, follow the steps given below. Use one of the below two methods.

Click on the Command Palette on the top of the VS Code.
Type > to show the available commands.
Select MI: Add MI server.
Select Add MI server.
Select the folder where <MI_HOME> is located. This wll be set as the current server path.
Run the project.

Use one of the following two options to build and run the project:

Option 1

Click on the Command Palette on the top of the VS Code.
Type > to show the available commands.
Select MI: Build and Run.

Option 2

Click the Build and Run icon located on the top right corner of the VS Code.

The artifacts will be deployed in the embedded Micro Integrator and the server will start.

See the startup log in the Console tab.
See the URLs of the deployed services and APIs in the Runtime Services tab.

Step 4: Test the use case¶

Let's test the use case by sending a simple client request that invokes the service.

Start the back-end service¶

Download the JAR file of the back-end service from here.
Open a terminal, and navigate to the location where you saved the back-end service.
Execute the following command to start the service:
```
java -jar Hospital-Service-JDK11-2.0.0.jar
```

Send the client request¶

Let's send a request to the API resource. You can use Postman or any other HTTP Client. Make sure you provide a valid email address so that you can test the email being sent to the patient.

Open the Postman application. If you do not have the application, download it from here : Postman

Add the request information as given below and click the Send button.

Method	`POST`
Headers	`Content-Type=application/json`
URL	`http://localhost:8290/healthcare/categories/surgery/reserve` The URI-Template format that is used in this URL was defined when creating the API resource: `http://:/categories/{category}/reserve`.
Body	`{ "patient": { "name": "John Doe", "dob": "1940-03-19", "ssn": "234-23-525", "address": "California", "phone": "8770586755", "email": "[email protected]", "cardNo": "7844481124110331" }, "doctor": "thomas collins", "hospital_id": "grandoaks", "hospital": "grand oak community hospital", "appointment_date": "2025-04-02" }` This JSON payload contains details of the appointment reservation, which includes patient details, doctor, hospital, and data of appointment.

If you want to send the client request from your terminal:

Install and set up cURL as your REST client.

Create a JSON file named request.json with the following request payload.

{
  "patient": {
  "name": "John Doe",
  "dob": "1940-03-19",
  "ssn": "234-23-525",
  "address": "California",
  "phone": "8770586755",
  "email": "[email protected]",
  "cardNo": "7844481124110331"
  },
  "doctor": "thomas collins",
  "hospital_id": "grandoaks",
  "hospital": "grand oak community hospital",
  "appointment_date": "2025-04-02"
}

Open a command line terminal and execute the following command from the location where the request.json file you created is saved:

curl -v -X POST --data @request.json http://localhost:8290/healthcare/categories/surgery/reserve --header "Content-Type: application/json"

Analyze the response¶

An email will be sent to the provided patient email address with the following details:

Subject: Appointment Status
             
Message: 
    {
        "appointmentNumber": 1,
        "doctor": {
            "name": "thomas collins",
            "hospital": "grand oak community hospital",
            "category": "surgery",
            "availability": "9.00 a.m - 11.00 a.m",
            "fee": 7000.0
        },
        "patient": {
            "name": "John Doe",
            "dob": "1940-03-19",
            "ssn": "234-23-525",
            "address": "California",
            "phone": "8770586755",
            "email": "[email protected]"
        },
        "fee": 7000.0,
        "confirmed": false
    }

You have now explored how to import the Email connector to the Micro Integrator and then use the connector operations to send emails.