Developing an Apache Wink REST Client for Bluemix Liberty Runtime

Share this post:

The JAX 1.1 standard does not specify a standard REST client implementation; web developers have a myriad of means to accomplish it. Apache Wink is one of the popular methods that web developers use when developing a REST client on a WebSphere Liberty environment, such as Bluemix Liberty runtime. This blog shows how to develop such a client using a web development tool (Eclipse) and deploy it to Bluemix.

Set up the Eclipse development environment

Before you get started, you will need to set up an Eclipse development environment on your local machine. Follow the online instructions below:

Implement REST service

Now that we have a working development environment, the next step is developing a REST service to be called by the REST client. In our sample, the REST service is implemented by following the instructions in REST Web Services in WebSphere Liberty, an excerpt from the book Modern Web Development with IBM WebSphere by Kyle Brown et al and published by IBM Press. Once you’ve completed these steps, continue to the next section.

Implement REST client

Now we are able to create and test a REST client for the REST service, which we just implemented, using Eclipse that has the Liberty profile setup as described earlier (I used Eclipse Luna version with IBM Bluemix Tools 1.0.1.v20141111_2000; you may have slightly different setup with you environment).

Create RestClientSample project

  • Open “Java EE” perspective, create a new web project from menu “File” → “New” → “Web Project”, and name the project, RestClientSample
  • Click on Next, ensure Liberty profile is chosen, and deselect “Add project to an EAR”
  • Highlight “Java” and ensure its setup as default as shown below
  • Highlight “Web Module”, and ensure its setup as shown below
  • Click on “Change Features…” and ensure that “JAX-RS (REST Web Services)” is selected
  • Click on “OK”, then click on “Finish” to create the project.

Create RestClientServlet

  • In “Java EE” perspective, “Enterprise Explorer” view, expand the newly created project, RestClientSample, expand “Java Resources” underneath and find ”src”; right click on it to create a new package from the popup menu, “New” → ”package” and then “Finish”
  • Click on the newly created package to create a new Servlet, RestClientServlet, as our REST client, “New” → ”Servlet”

  • Click on “Next” ensure “URL mapping” is named properly

  • Click on “Next”, ensure “doGet” is checked, uncheck “doPost, and then click on “Finish”.

Implement RestClientServlet.doGet method

In “Enterprise Explorer” view, double click on to open it in Java editor. Implement the doGet method as shown below. The API details are in the infoCenter and Apache.

Notice the line of code client = new RestClient(clientConfig) creates an Apache Wink REST client with predefined client configuration parameters, which are default in this case. The line resource = client.resource("") creates a resource based on the REST service URL. The URL shows that the REST service has been deployed to Bluemix as If the REST service has not been deployed to Bluemix and runs on a local Liberty test environment in Eclipse, this URL would have been similar to http://localhost:9080/RestServicesSamples/banking/Greeting. Finally, resp = resource.get() makes the REST GET call to the service.

Set up server for REST client

If you would like to run your REST client on a new WebSphere Liberty server in Eclipse, follow the steps below.

  • In the “Servers” view, right click, “New” → ”Server”
  • Click on “Next”, click on “New” next to “Liberty Profile Server” to create a new profile server, libertyProfileServer
  • Click on “Finish”. Click on “Next”, highlight RestClientSample project, click on “Add”, and then “Finish”.
  • In “Servers” view, double click on “WebSphere Liberty Server” to open its configuration, click on “Open Server configuration”
  • In the “Design” view, choose Feature Manager and ensure jaxrs-1.1 is selected.
  • Save all changes, before closing the server editor.

Since Apache Wink Client runtime support is a 3rd-party add-on, in WebSphere Liberty 8.5, the follow configuration is needed to turn on its support. In “Enterprise Explorer” view, “WebSphere Application Server V8.5 Liberty Profile” → ”Servers” → ”libertyProfileServer” → ”server.xml”, open server.xml in text editor and modify the following line:

<webApplication id="RestClientSample" location="RestClientSample.war" name="RestClientSample"/>


<webApplication id="RestClientSample" location="RestClientSample.war" name="RestClientSample">
<classloader apiTypeVisibility="spec, ibm-api, third-party"/>

Note libertyProfileServer is the new profile server created in the prior steps to run the client. If you use a different server name, modify its server.xml accordingly

  • In “Enterprise Explorer” view, Right click on RestClientSample, “Run As” → “Run on Server”, choose “WebSphere Liberty Server” as shown below, and then “Finish”. “WebSphere Liberty Server” is the server created previously.
  • Check the console to confirm the server launched successfully

Deploy REST client to Bluemix

Almost done! In “Servers” view, stop “WebSphere Liberty Server”, if it is started, then follow the steps below:

  • If the Eclipse tools for Bluemix plugin is installed, right click on “WebSphere Liberty Server” → “Utilities” → “package server to IBM Bluemix”
  • Click on “OK”.
  • Choose an unique name for the application as shown below, replacing “xxx” with an unique identifier

    Note: if the name chosen is not unique, user will get “404 bad request, hostname taken” error during the process of deploying the application to Bluemix.
  • Click on Next, choose “Start application on deployment”, so that the application is started, when it is deployed
  • Click on “Finish” and invoke the deployed client using
    Note, change “xxx” to your unique identifier

If Eclipse tools for Bluemix plugin is not installed, the application should be deployed to Bluemix as “a packaged server” using cf commands, as specified in Options for pushing Liberty Applications. Please follow the instructions for “Pushing a packaged server”.

More stories
April 23, 2019

Introducing Private Service Endpoints in IBM Cloud Databases

We recently released an update to all IBM Cloud Databases which allows you to enable public and/or private service endpoints for your database deployments. In this post, we’ll walk you through the setup.

Continue reading

April 19, 2019

Reach Out to the IBM Cloud Development Teams on Slack

Get the help you need fast—directly from the IBM Cloud Development Teams and other users on Slack.

Continue reading

April 19, 2019

Introducing IBM Cloud Object Storage Firewall: Further Secure Your Data

IBM Cloud Object Storage (COS) is giving you more control over who can access your data. We have introduced a new capability allowing you to configure your buckets with trusted IP address(es) that will dictate access to the data in COS.

Continue reading