This documentation is for WSO2 Enterprise Service Bus version 5.0.0. For the latest ESB, view the latest WSO2 Enterprise Integrator documentation.

All docs This doc
Skip to end of metadata
Go to start of metadata

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. We will configure an API resource in ESB that will receive the client request, instead of the client sending messages directly to the back-end service, thereby decoupling the client and the back-end service.

In this tutorial, you create a REST API in WSO2 ESB to connect to a REST back-end service that is defined as a HTTP Endpoint in WSO2 ESB.

Before you begin,

  1. Install Oracle Java SE Development Kit (JDK) version 1.8.* and set the JAVA_HOME environment variable.
  2. Go to, click DOWNLOAD to download the ESB runtime ZIP file, and then extract the ZIP file. 
    The path to this folder will be referred to as <ESB_HOME> throughout the tutorials.
  3. Go to, click Tooling to select and download the relevant ESB tooling ZIP file, and then extract the ZIP file. 
    The path to this folder will be referred to as <TOOLING_HOME> throughout the tutorials. 

    For more detailed installation instructions, see the Installing WSO2 ESB Tooling.

To start Eclipse on a Mac for the first time, open a terminal and execute the following commands:

chmod +x eclipse 

Thereafter, you can start Eclipse by double-clicking the Eclipse icon in <TOOLING_HOME> .

Let's get started!

This tutorial includes the following sections:

Creating the message mediation artifacts

Requests going through the ESB are called messages, and message mediation is a fundamental part of any ESB. In this section, we will configure message mediation for requests received by the ESB that need to be sent to the HealthcareService back-end service. We will use Eclipse based WSO2 ESB Tooling to create the message mediation artifacts and then deploy them to WSO2 ESB.

See the following topics for a description of the concepts that you need to know when creating ESB artifacts:

Creating the deployable artifacts project

  1. In Eclipse, open the Developer Studio dashboard by clicking the Developer Studio menu and choosing Open Dashboard

  2. Click ESB Solution Project and create a project named SampleServices and select the following check boxes so that the relevant projects will be created.

    • Create Registry Resources Project
    • Create Connector Exporter Project
    • Create Composite Application Project

    Click Finish.

    You have now created the following ESB related projects as shown in the Project Explorer:


Next, inside the SampleServices ESB Config project, we will create an endpoint that will allow the ESB to connect to the back-end service.

Connecting to the back-end service 

The sample back-end service used in this tutorial (i.e. the Hospital-Service-2.0.0.jar file) is hosted in WSO2 App Cloud. To connect to this back-end service you must expose a URL that can be used to connect to the service. To do this, create an endpoint for this service.

  1. Right-click SampleServices in the Project Explorer and navigate to New -> Endpoint.

  2. Ensure Create a New Endpoint is selected and click Next. Give the information as in the table below:

    Endpoint NameQueryDoctorEPThe name of the endpoint defined.
    Endpoint TypeHTTP EndpointIndicates that we are connecting to REST back-end service.
    URI Template{uri.var.category}The template for the request URL expected by Healthcare 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. 
    MethodGETIndicates that we are creating this endpoint for GET requests that are sent to the back-end service.
    Static Endpoint
    Select this option because we are going to use this endpoint in this ESB project only and will not re-use it in other projects. If you need to create a reusable endpoint, you create it as a Dynamic Endpoint and save the endpoint in either the Configuration or Governance Registry. For more information, see the documentation on registries.
    Save Endpoint inSampleServicesThis is the ESB Config project we created in the last section

    Click Finish

    The QueryDoctorEP endpoint you created is saved in the endpoints folder within the ESB Config Project you created.

Now that you have created the endpoint for the back-end service, it’s time to create the REST API and the relevant API resource that will receive requests from client applications, mediate them and send them to the endpoint, and return the results to the client.

Mediating requests to the back-end service

We will use WSO2 ESB Tooling to create a REST API named HealthcareAPI. We will then create a resource within this API for the GET HTTP method that is used to send requests to the HealthcareService back-end service and retrieve available doctor information.

  1. In the Project Explorer, right-click SampleServices and navigate to New -> REST API.

  2. Ensure Create A New API Artifact is selected and click Next.

  3. Fill in the information as in the table below:

    NameHealthcareAPIThe name of the REST API in WSO2 ESB
    Context/healthcareHere we are anchoring the API at "/healthcare" context. This will become part of the name of the generated URL used by the client when sending requests to HealthcareService. For example, setting the context to /healthcare defines that the API will only handle HTTP requests whose URL path starts with http://<host>:<port>/healthcare.
    Save locationSampleServicesThis is the ESB Config project we have already created previously.

    Click Finish. Once the API resource is created, the design view of the HealthcareAPI.xml file appears so that you can start configuring the API resource. 

    The top part of the canvas is the In sequence, which controls how incoming messages are mediated. 

    The middle part of the canvas is the Out sequence, which controls how responses are handled. In this case, a Send mediator is already in place to send responses back to the requesting client.

    The bottom part of the canvas is the Fault sequence, which allows you to configure how to handle messages when an error occurs (for more information, see Error Handling).

  4. Click the Resource icon on the left side of the canvas. The properties for the API resource will appear on the Properties tab at the bottom of the window. (If they do not appear, you can right-click the proxy icon and click Show Properties View.)

  5. On the Properties tab provide the following in the Basic property:
    • Url Style: Click in the Value field, click the down arrow, and then select URI_TEMPLATE from the list
    • URI-Template: /querydoctor/{category}
      This defines request URL format. In this case, the full request URL format is http://<host>:<port>/querydoctor/{category} where {category} is a variable. 

  6. In the Methods section of the properties tab, set the value of Get to true. This defines that the API resource created handles only requests where the HTTP method is GET.

    We are now ready to configure In sequence to handle requests from the client. 

    You can use the Log mediator to log a message when the request is received by the In sequence of the API resource. In this scenario, we will configure the Log mediator display the message “Welcome to the HealthcareService”.

  7. From the Mediators palette, click and drag a Log mediator to the In sequence (the top of the canvas).
  8. With the Log mediator selected, access the Properties tab and fill in the information in the table below:

    Log CategoryINFOIndicates that the log contains an informational message.
    Log LevelCustomWhen 'Custom' is selected, only specified properties will be logged by this mediator.
    Log Seperator(blank)Since there is only one property that is being logged, we do not require a separator, so this field can be left blank.
    We will add the property in the next step, so skip this for now.
    DescriptionRequest LogThe Description field provides the name that appears for the Log mediator icon in the design view.
  9. We will now add the property that will extract the stock symbol from the request and print a welcome message in the log. Click the Value field of the Properties property, and then click the browse (...) icon that appears.
  10. In the Log Mediator Configuration dialog, click New, and then add a property called "message" as follows:
    • Name: message
    • Type: LITERAL
      We select LITERAL because the required the log message is a static value.
    • Value/Expression: "Welcome to HealthcareService"

    Click OK to save the Log mediator configuration.

    We will now configure the Send Mediator to send the request message to the HealthcareService endpoint.

  11. From the Mediators palette, click and drag a Send mediator to the In sequence adjoining the Log mediator you added above. Adjoining this, click and drag the QueryDoctorEP we created above the Defined EndPoints palette.

    The In Sequence is now complete. Next, we need to ensure that we send the response from the HealthcareService endpoint back to the client. For this, we use a Send mediator with no output endpoint defined, which defaults to sending the response back to the requesting client. 

  12. From the Mediators palette, click and drag a Send mediator to the Out Sequence (the bottom part of the canvas).


This completes the steps for creating the artifacts required for sending a request through WSO2 ESB to the HealthcareService back-end service. We will now package these artifacts and deploy them to WSO2 ESB.

Deploying the artifacts to WSO2 ESB

  1. Package the QueryDoctorEP endpoint and HealthcareAPI resource into the Composite Application (C-App) project named SampleServicesCompositeApplication. Save all changes.

    The SampleCApp Composite Application project is generated and is listed under SampleApp project in the Project Explorer. The Composite Application Project POM Editor can be accessed by selecting the pom.xml file listed under SampleServicesCompositeApplication project.

  2. In ESB Tooling, navigate to Developer Studio Dashboard and click Server under Add Server.
  3. In the Define a New Server dialog box, expand the WSO2 folder, and select the version the WSO2 ESB server.Select WSO2 ESB Server 5.0.0.
  4. Click Next, provide the path to your ESB home (the directory where you installed WSO2 ESB) in the CARBON_HOME field, and then click Next again. 
  5. Review the default port details for WSO2 ESB. Typically, you can leave these unchanged, but if you are already running another server on these ports, specify unused ports here. (See Default Ports of WSO2 Products for more information.) Click Next
  6. To deploy the CApp project to the WSO2 ESB server we just added, select SampleServicesCompositeApplication from the list, click Add to move it into the Configured list, and then click Finish.

    The WSO2 ESB server is now added inside Eclipse ESB tooling.

    On the Servers tab, you can see that the server is currently stopped. Click the "start the server" icon on the Servers tab's toolbar. If prompted to save changes to any of the artifact files you created earlier, click Yes

    As the server starts, the Console tab will appear. You should see messages indicating that SampleCApp_1.0.0 was successfully deployed. The C-App will now be available in the ESB management console in Manage -> Carbon Applications -> List.

    You can also deploy the artifacts to the ESB server using a Composite Application Archive (CAR) file.

Sending requests to WSO2 ESB

Let's send a request to our REST API, HealthcareAPI, which is now deployed in WSO2 ESB. You will need a REST client like curl for this.

  1. In your Web browser, navigate to the WSO2 ESB management console using the following URL: https://localhost:9443/carbon/. (If you changed the ports, replace "9443" with the correct HTTPS port.)
  2. Log into the management console using the following credentials:
    • Username: admin
    • Password: admin
  3. In the left navigation pane, click APIs under Service Bus. Here you can see that the REST API we created earlier, HealthcareAPI, is available in the ESB and is ready to receive requests and send them to the back-end service. Here you can also view the API Invocation URL that is used in to send the request to the service.

  4. Open a command line terminal and enter the following request:

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

    This is derived from the URI-Template defined when creating the API resource.


    Other categories you can try sending in the request are:

    • cardiology

    • gynaecology

    • ent

    • paediatric

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

    [{"name":"thomas collins",
      "hospital":"grand oak community hospital",
      "availability":"9.00 a.m - 11.00 a.m",
     {"name":"anne clement",
      "hospital":"clemency medical center",
      "availability":"8.00 a.m - 10.00 a.m",
     {"name":"seth mears",
      "hospital":"pine valley community hospital",
      "availability":"3.00 p.m - 5.00 p.m",
  6. Now, check the ESB server Console in Eclipse, and you will see the following message: 
    INFO - LogMediator message = "Welcome to HealthcareService"

    This is the message printed by the Log mediator when the message from the client is received in the In sequence of the API resource.

You have now created and deployed an API resource in WSO2 ESB that 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. 

  • No labels