Skip to content

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.

  1. Launch VS Code with the Micro Integrator extension installed.

  2. Click on the Micro Integrator icon on the Activity Bar of the VS Code editor.

    MI VS Code Extension

  3. Click Create New Project on Design View.

    Design View Pane Create New Project

    Next, the Project Creation Form will be opened.

  4. In the Project Creation Form, enter ExposeSeveralServicesTutorial as the Project Name.

  5. Provide a location under Select Project Directory.

    create new project

  6. 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.

  1. Navigate to the MI Project Explorer > Endpoints.

    create new endpoint

  2. Hover over Endpoints and click the + icon that appears.

    Add endpoint

  3. Next, select HTTP Endpoint type from the Create Endpoint Artifact interface.

    Create HTTP Endpoint

  4. 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.

  5. Click Create.

  6. 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.

  7. Click Create.

  8. 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.

  9. Click Create.

You have now created the endpoints that are required for this tutorial.

Create a REST API

  1. Go to MI Project Explorer > APIs.

    create new api

  2. Hover over APIs and click the + icon that appears to open the API Form.

    add API

  3. 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.

    synapse API artifact

  4. Click Create. This opens the Service Designer interface.

    You can now start configuring the API resource.

  5. 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.

  6. Click the Edit icon to edit the API resource.

    edit icon

  7. Specify values for the required resource properties:

  8. 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.
    8. Click Update.

Update the mediation flow

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

  1. To get started, click on the + icon to add the first mediator to the sequence.

  2. Select Property mediator from the Mediators palette. This is used to extract the hospital name that is sent in the request payload.

    add property mediator

  3. 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)
    1. Click the Ex button before the Value field. This specifies the value type as expression.
    2. Enter json-eval($.hospital_id) as the expression value.
    Note: This is the JSONPath expression that will extract the hospital from the request payload.

  4. Click Submit.

  5. 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.

  6. 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)
    1. Click the Ex button before the Value field. This specifies the value type as expression.
    2. Enter json-eval($.cardNo) as the expression value.
    Note: This is the JSONPath expression that will extract the card number from the request payload.
    Description Get Card Number The description of the property.

  7. 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:

    {
        "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
    }
    
    Let's use Property mediators to retrieve and store the values that you get from the response you receive from GrandOakEP, ClemencyEP, or PineValleyEP.

    add call mediator

  8. Add another Property mediator after Call mediator to retrieve and store the value sent as appointmentNumber.

  9. 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)
    1. Click the Ex button before the Value field. This specifies the value type as expression.
    2. Enter json-eval($.appointmentNumber) as the expression value.
    Note: This is the JSONPath expression that will extract the appointment number from the request payload.
    Description Get Appointment Number The description of the property.

  10. Similarly, add two more Property mediators. They will retrieve and store the doctor details and patient 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)
      1. Click the Ex button before the Value field. This specifies the value type as expression.
      2. Enter json-eval($.doctor) as the expression value.
      Note: This is the JSONPath expression that will extract the doctor details from the request payload.
      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)
      1. Click the Ex button before the Value field. This specifies the value type as expression.
      2. Enter json-eval($.patient) as the expression value.
      Note: This is the JSONPath expression that will extract the patient details from the request payload.
      Description Get Patient Details The description of the property.

  11. 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"
    }
    

  12. Add a Property mediator adjoining the Call mediator box to retrieve and store the value sent as actualFee

  13. 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)
    1. Click the Ex button before the Value field. This specifies the value type as expression.
    2. Enter json-eval($.actualFee) as the expression value.
    Description Get Actual Fee The description of the property.

  14. 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"
    }
    
  15. Add a PayloadFactory mediator next to the Property mediator to construct the above message payload.

    add payload mediator

  16. 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
    {"appointmentNumber":$1, "doctor":$2, "patient":$3, "fee":$4, "confirmed":"false", "card_number":"$5"}
    
    This is the message payload to send with the request to SettlePaymentEP. In this payload, $1, $2, $3, $4, and $5 indicate variables.

  17. To add the arguments for the PayloadFactory mediator:

  18. Click the Add Parameter in the Args field to open the PayloadFactoryArgument dialog.
  19. 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:

    1. Click the Ex button before the Value field. This specifies the value type as expression.
    2. Enter $ctx:uri.var.appointment_id as the expression. Note that the $ctx method is similar to using the get-property method. This method checks in the message context.
    Evaluator Select xml.

    This indicates that the expression is provided in XML.

    payload mediator parameters

  20. Click Save.

  21. 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
  22. Click Submit.

  23. Add a Call mediator from the Mediators palette.In the sequence palette specify the endpoint as SettlePaymentEP. Click Submit.

  24. 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:

  1. 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.

  2. 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.

  1. Click on the Command Palette on the top of the VS Code.

  2. Type > to show the available commands.

  3. Select MI: Add MI server.

  4. Select Add MI server.

  5. Select the folder where <MI_HOME> is located. This wll be set as the current server path.

    Current server path

  6. Run the project.

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

    Build and run

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

  1. Download the JAR file of the back-end service from here.
  2. Open a terminal, navigate to the location where you saved the back-end service.
  3. 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:

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

  2. 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.

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

  1. Install and set up cURL as your REST client.
  2. 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]"
      },
      "doctor": "thomas collins",
      "hospital_id": "grandoaks",
      "hospital": "grand oak community hospital",
      "cardNo": "7844481124110331",
      "appointment_date": "2025-04-02"
    }
    
    3. Open a terminal and navigate to the directory where you have saved the request.json file.

  3. 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.