Learn how to use MicroProfile Rest Client to invoke RESTful services over HTTP in a type-safe way.
You will learn how to retrieve information from a remote service with MicroProfile Rest Client. MicroProfile Rest Client provides a type-safe way to call RESTful services so that developers can focus more on the client models rather than how to connect with remote services while developing client applications.
The application that you will be working with is an inventory service which retrieves and stores the system property information for different hosts.
Whenever a request is made to the inventory service to retrieve the
system properties of a particular host, the inventory service will create a client to invoke the system
service on that host to get these system properties. The system service simulates a remote service in this application.
You will learn how to create and register the client interface and handle exceptions through ResponseExceptionMappers.
In addition, you will build the implementation of the RESTful client with two approaches: RestClientBuilder, or Contexts and Dependency Injection (CDI).
The finish directory in the root of this guide contains the finished inventory application. Feel
free to give it a try before you proceed.
To try out the application, first navigate to the finish directory and then run the following
Maven goals to build the application and run it inside Open Liberty:
mvn install liberty:start-serverAfter starting the application, you can access the following two microservices:
-
http://localhost:9080/system/propertiesretrieves the information for a specific host -
http://localhost:9080/inventory/systemsretrieves the information for a list of all previously registered hosts
Once you are done checking out the application, stop the Open Liberty server:
mvn liberty:stop-serverNow, navigate back to the start directory to begin.
The MicroProfile Rest Client API was added as a dependency to your pom.xml file. Look for the dependency with the microprofile-rest-client-api artifact ID.
This feature allows you to use the MicroProfile Rest Client to invoke RESTful services over HTTP in a type-safe way.
The mpRestClient-1.0 feature is also enabled in the src/main/liberty/config/server.xml file.
The code for the system service in the src/main/java/io/openliberty/guides/system directory is provided for you. It simulates a remote RESTful service that
the inventory service tries to invoke.
Now you need to create a RESTful client interface that represents this system service, call it the system client.
Create a src/main/java/io/openliberty/guides/inventory/client/SystemClient.java file:
link:finish/src/main/java/io/openliberty/guides/inventory/client/SystemClient.java[role=include]Note that the service will automatically build and generate an implementation for the system client interface, because the JAX-RS annotations in this interface tells the RESTful service what to do. That allows the user to not have to worry about all of the boilerplate code (like setting up a client class, connecting to the remote server, invoking the right URI with the right parameters, etc.).
When the getProperties() method gets invoked, the system client sends a GET request to the endpoint at <baseUrl>/system/properties.
Now you need to instantiate the system client and use it in the inventory service. It is easy to do so using the CDI and MicroProfile Config approach.
First, you need to configure the baseUrl of this system client using MicroProfile Config. The feature has been enabled for you in both server.xml and pom.xml files.
Open the finish/pom.xml file, add a new config property called <fullyQualifiedInterfaceName>/mp-rest/url which in this case is io.openliberty.guides.service.MusicPlaylistService/mp-rest/url to the <bootstrapProperties> field and
configure this property to the default base URL http://localhost:9080/system/properties. This configuration will be automatically picked up by the MicroProfile Config API.
Then, update the src/main/java/io/openliberty/guides/inventory/client/SystemClient.java file with a few more annotations:
link:finish/src/main/java/io/openliberty/guides/inventory/client/SystemClient.java[role=include]@Dependent tells the service the scope of this interface.
@RegisterRestClient registers this interface as a rest client.
@RegisterProvider() adds any provider classes to this interface; you can add as many providers as necessary.
Inject the system client to the InventoryResource class using CDI. Copy all the following code and replace the contents of the src/main/java/io/openliberty/guides/inventory/InventoryResource.java file:
link:finish/src/main/java/io/openliberty/guides/inventory/InventoryResource.java[role=include]@RestClient implies that CDI injects an instance of the system Rest Client to the service.
Now you can invoke the system service by calling the systemClient.getProperties() method.
Once the server is running, the following two microservices should be available to access:
Create a src/test/java/it/io/openliberty/guides/client/RestClientTest.java file and add the following code:
link:finish/src/test/java/it/io/openliberty/guides/client/RestClientTest.java[role=include]In addition, a few endpoint tests have been provided for you to test the basic functionality of the inventory and system services. If a test failure occurs, then you must have introduced a bug into the code.
-------------------------------------------------------
T E S T S
-------------------------------------------------------
Running it.io.openliberty.guides.config.RestClientTest.java
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.729 sec - in it.io.openliberty.guides.config.ConfigurationTest
Running it.io.openliberty.guides.inventory.InventoryEndpointTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.477 sec - in it.io.openliberty.guides.inventory.InventoryEndpointTest
Running it.io.openliberty.guides.system.SystemEndpointTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.013 sec - in it.io.openliberty.guides.system.SystemEndpointTest
Results :
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0To see whether the tests detect a failure …… Re-run the Maven build. You will see a test failure occur.
You just built and tested a MicroProfile application with MicroProfile Rest Client and Open Liberty.
Feel free to try one of the related guides. They demonstrate new technologies that you can learn and expand on top what you built in this guide.