How to Send a Simple Message to a Service¶

What you'll build¶

Let’s try a simple scenario where a patient makes an inquiry specifying the doctor's specialization (category) to retrieve a list of doctors that match the specialization. The required information is available in a back-end microservice.

To implement this use case, you will create a REST API resource and other artifacts using Micro Integrator Extension for Visual Studio Code (MI for VS Code), and then deploy them in the embedded WSO2 Micro Integrator instance. The default API resource will be configured to receive the client request in place of the back-end service, thereby decoupling the client and the back-end service. The response message with the requested doctor details will be routed back to the client through the same API resource.

Concepts and artifacts used¶

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): 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¶

Follow the instructions given in this section to create and configure the required 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 SimpleMessageTutorial 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 for the purpose of exposing 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	`QueryDoctorEP`	The name of the endpoint.
URI Template	`http://localhost:9090/healthcare/{uri.var.category}`	The template for the request URL expected by the back-end service. In this case, the variable 'category' that needs to be included in the request for querying doctors is represented as `{uri.var.category}` in the template.
Method	`GET`	Indicates that we are creating this endpoint for GET requests that are sent to the back-end service.

Click Create.

The QueryDoctorEP endpoint is saved in the endpoints folder inside the <PROJECT_NAME>/src/main/wso2mi/artifacts directory.

Once the endpoint artifact is created, it will appear on the MI Overview interface.

Create a REST API¶

A REST API is required for receiving the client response and the REST resource within the API will define the mediation logic that will send requests to the Healthcare back-end service and retrieve the available doctor information.

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 opens 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	`/querydoctor/{category}` This defines the request URL format. In this case, the full request URL format is `http://host:port/querydoctor/{category}` where `{category}` is a variable.
URL Style	`URI_TEMPLATE`
Methods	`GET` This defines that the API resource only handles requests where the HTTP method is GET.

Click Update.

Create the mediation logic¶

You can now configure the mediation logic to handle requests.

To get started, click on the + icon to add the first mediator to the sequence.
Select Log mediator in the Generic section under All Mediators.

Note

The Log mediator logs messages when the request is received by the API resource. In this scenario, let's configure the Log mediator to display the following message: “Welcome to the HealthcareService”.

Once you select the Log mediator, the Log pane will be opened. Fill in the information in the table below:

Field	Value	Description
Log Category	`INFO`	Indicates that the log contains an informational message.
Log Level	`Custom`	When `Custom` is selected, only specified properties will be logged by this mediator.
Log Separator	`(blank)`	Since there is only one property that is being logged, you do not require a separator. Therefore, leave this field blank.
Properties		1. To edit the Properties and print a welcome message in the log, click Add Parameter. , 2. Then add the following values: Property Name: `Log Property message` Property Value : `"Welcome to HealthcareService"` 3. Click Save to save the properties.
Description	`Request Log`	The Description field provides the name that appears for the Log mediator icon in the design view.

Click Submit to save the Log mediator configuration.

Let's configure a Call mediator to send the request message to the HealthcareService endpoint and receive the response message.
Click on the + icon in the sequence to add a Call mediator after the Log mediator.
From the Palette, select Call Endpoint mediator under the Mediators > Generic section.
From the Call Endpoint pane, select the QueryDoctorEP endpoint, which we created in a previous step.
Click Submit.

Now let's add a Respond mediator at the end of the in sequence to send the response message from the healthcare service back to the client.
Click on the + icon in the sequence to add a Respond mediator after the Call mediator.
From the Palette, select Respond mediator under the Mediators > Generic section.
Click Submit.

You have successfully created all the artifacts that are required for sending a request through the Micro Integrator to the back-end service.

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.

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

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, navigate to the location where your 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 the request to the API. You can use the embedded HTTP Client as follows:

Open the Postman application. If you do not have the application, download it from here.
Add the request information as given below and click the Send button.

Method GET

URL http://localhost:8290/healthcare/querydoctor/surgery

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

Install and set up cURL as your REST client.

Execute the following command.

curl -v http://localhost:8290/healthcare/querydoctor/surgery

Analyze the response¶

You will see the response message from the HealthcareService with a list of available doctors and the relevant details.

[
   {
      "name": "thomas collins",
      "hospital": "grand oak community hospital",
      "category": "surgery",
      "availability": "9.00 a.m - 11.00 a.m",
      "fee": 7000.0
   },
   {
      "name": "anne clement",
      "hospital": "clemency medical center",
      "category": "surgery",
      "availability": "8.00 a.m - 10.00 a.m",
      "fee": 12000.0
   },
   {
      "name": "seth mears",
      "hospital": "pine valley community hospital",
      "category": "surgery",
      "availability": "3.00 p.m - 5.00 p.m",
      "fee": 8000.0
   }
]

Now, check the Output tab of VS Code and you will see a message similar to the following:

[2024-07-29 15:51:36,956]  INFO {LogMediator} - {api:HealthcareAPI} Log Property message = "Welcome to HealthcareService"

You have now created and deployed an API resource in the Micro Integrator, which receives requests, logs a message using the Log mediator, sends the request to a back-end service using the Send mediator, and returns a response to the requesting client.

Method	`GET`
URL	`http://localhost:8290/healthcare/querydoctor/surgery`