How to Expose Several Services as a Single Service¶
What you'll build¶
When information from several services is required to construct a response to a client request, service chaining needs to be implemented. This means integrating several services based on some business logic and exposing them as a single, aggregated service.
In this tutorial, when a client sends a request for a medical appointment, the Micro Integrator performs several service calls to multiple back-end services to construct a response that includes all the necessary details. The Call mediator allows you to specify all service invocations one after the other within a single sequence.
You will also use the PayloadFactory mediator to take the response from one back-end service and transform it into the format accepted by another back-end service.
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
ExposeSeveralServicesTutorial
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 new Endpoints¶
Let's create three HTTP endpoints to represent all three back-end services: Hospital Service, Channeling Service, and Payment 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 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. -
Click Create.
-
Create another HTTP Endpoint for the Channeling back-end service and specify the details given below:
Property Value Description Endpoint Name ChannelingFeeEP
The name of the endpoint. URI Template http://localhost:9090/{uri.var.hospital}/categories/appointments/{uri.var.appointment_id}/fee
The template for the request URL expected by the back-end service. The following two variables will be replaced by the corresponding values in the request message: - {uri.var.hospital}: This will be the hospital ID extracted from the original request payload.
- {uri.var.appointment_id}: This will be the appointment ID extracted from the response payload that is received from the hospital service.
Method GET
This endpoint artifact will be used to get information from the back-end service. -
Click Create.
-
Create another HTTP Endpoint for the Settle Payment back-end service and specify the details given below:
Property Value Description Endpoint Name SettlePaymentEP
The name of the endpoint. URI Template http://localhost:9090/healthcare/payments
The template for the request URL expected by the back-end service. Method POST
This endpoint artifact will be used to post information to the back-end service. -
Click Create.
You have now created the endpoints that are required for this tutorial.
Create a 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 withhttp://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 Value Description URI-Template /categories/{category}/reserve
The request URL should match this template. The {category} variable will be replaced with the value sent in the request. Url Style URI_TEMPLATE
You can now specify dynamic variables to extract values from the request URL. Methods POST
This API resource will accept POST requests. Update the mediation flow¶
You can now start updating the API resource with the mediation flow.
-
To get started, click on the + icon to add the first mediator to the sequence.
-
Select Property mediator from the Mediators palette. This is used to extract the hospital name that is sent in the request payload.
-
With the Property mediator selected, access the Properties tab and give the following details:
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 property data type. Property Scope default
The scope of the property. Value (Expression) json-eval($.hospital_id)
- Click the Ex button before the Value field. This specifies the value type as expression.
-
Enter
json-eval($.hospital_id)
as the expression value.
-
Click Submit.
-
Add a new Property mediator just after the previous property mediator. This will retrieve and store the card number that was sent to the request payload.
-
With the Property mediator selected, access the Properties tab and specify the following details:
Property Value Description Property Name card_number
The name of the property, which will be used to refer to this property. Property Action set
The property action. Property Data Type String
The property data type. Value (Expression) json-eval($.cardNo)
- Click the Ex button before the Value field. This specifies the value type as expression.
- Enter
json-eval($.cardNo)
as the expression value.
Description Get Card Number The description of the property. -
Add a Call mediator from the Mediators palette. In the sequence palette, specify the endpoint as
HospitalServicesEP
. 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:
Let's use Property mediators to retrieve and store the values that you get from the response you receive 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 after Call mediator to retrieve and store the value sent as
appointmentNumber
. -
With the Property mediator selected, access the Properties tab and specify the following details:
Property Value Description Property Name uri.var.appointment_id
This value is used when invoking ChannelingFeeEP Property Action Select set
The action of the property Property Data Type String
The property data type. Value (Expression) json-eval($.appointmentNumber)
- Click the Ex button before the Value field. This specifies the value type as expression.
- Enter
json-eval($.appointmentNumber)
as the expression value.
Description Get Appointment Number The description of the property. -
Similarly, add two more Property mediators. They will retrieve and store the
doctor
details andpatient
details respectively from the response that is received from GrandOakEP, ClemencyEP, or PineValleyEP.-
To store
doctor
details:Property Value Description Property Name doctor_details
The property name that will be used to refer to this property. Property Action set The property action name. Property Data Type String
The property data type. Value (Expression) json-eval($.doctor)
- Click the Ex button before the Value field. This specifies the value type as expression.
- Enter
json-eval($.doctor)
as the expression value.
Description Get Doctor Details The description of the property. -
To store
patient
details:Property Value Description Property Name Enter patient_details
The property name that will be used to refer to this property. Property Action Select set The property action name. Property Data Type String
The property data type. Value (Expression) json-eval($.patient)
- Click the Ex button before the Value field. This specifies the value type as expression.
- Enter
json-eval($.patient)
as the expression value.
Description Get Patient Details The description of the property.
-
-
Add a Call mediator from the Mediators palette. In the sequence palette specify the endpoint as
ChannelingFeeEP
. Click Submit.Note
The following response that is received from ChannelingFeeEP:
{ "patientName": " John Doe ", "doctorName": "thomas collins", "actualFee": "7000.0" }
-
Add a Property mediator adjoining the Call mediator box to retrieve and store the value sent as
actualFee
. -
Access the Property tab of the mediator and specify the following details:
Property Value Description Property Name actual_fee
This value is used when invoking the SettlePaymentEP. The property name that will be used to refer to this property. Property Action set
The property action name. Property Data Type String
The property data type. Value (Expression) json-eval($.actualFee)
- Click the Ex button before the Value field. This specifies the value type as expression.
- Enter
json-eval($.actualFee)
as the expression value.
Description Get Actual Fee The description of the property. -
Let's use the PayloadFactory mediator to construct the following message payload for the request sent to SettlePaymentEP.
{ "appointmentNumber": 2, "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, "card_number": "1234567890" }
-
Add a PayloadFactory mediator next to the Property mediator to construct the above message payload.
-
With the PayloadFactory mediator selected, access the properties tab of the mediator and specify the following details:
Property Description Payload Format Select Inline
Media Type Select json
Payload This is the message payload to send with the request to SettlePaymentEP. In this payload, $1, $2, $3, $4, and $5 indicate variables.{"appointmentNumber":$1, "doctor":$2, "patient":$3, "fee":$4, "confirmed":"false", "card_number":"$5"}
-
To add the arguments for the PayloadFactory mediator:
- Click the Add Parameter in the Args field to open the PayloadFactoryArgument dialog.
-
Enter the following information in the PayloadFactoryArgument dialog box. This provides the argument that defines the actual value of the first variable (used in the format definition given in the previous step).
Property Description Argument Value Follow the steps given below to specify the expression:
- Click the Ex button before the Value field. This specifies the value type as expression.
-
Enter
$ctx:uri.var.appointment_id
as the expression. Note that the$ctx
method is similar to using theget-property
method. This method checks in the message context.
Evaluator Select xml
. This indicates that the expression is provided in XML. -
Click Save.
-
Similarly, click Add Parameter and add more arguments to define the other variables that are used in the message payload format definition. Use the following as the Value for each of them:
$ctx:doctor_details
$ctx:patient_details
$ctx:actual_fee
$ctx:card_number
-
Click Submit.
-
Add a Call mediator from the Mediators palette.In the sequence palette specify the endpoint as
SettlePaymentEP
. Click Submit. -
Add a Respond mediator to send the response to the client.
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 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:
-
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 date of appointment.
-
The URI-Template format that is used in this URL was defined when creating the API resource:
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.3. Open a terminal and navigate to the directory where you have saved the{ "patient": { "name": "John Doe", "dob": "1940-03-19", "ssn": "234-23-525", "address": "California", "phone": "8770586755", "email": "[email protected]" }, "doctor": "thomas collins", "hospital_id": "grandoaks", "hospital": "grand oak community hospital", "cardNo": "7844481124110331", "appointment_date": "2025-04-02" }
request.json
file. -
Execute the following command.
curl -v -X POST --data @request.json http://localhost:8290/healthcare/categories/surgery/reserve --header "Content-Type:application/json"
Analyze the response¶
You will see the response received to your HTTP Client:
{ "patient":"John Doe", "actualFee":7000.0, "discount":20, "discounted":5600.0, "paymentID":"480fead2-e592-4791-941a-690ad1363802", "status":"Settled" }
You have now explored how the Micro Integrator can perform service chaining using the Call mediator and transform message payloads from one format to another using the PayloadFactory mediator.