![[18.0.0.1 and later]](../ng_v18001plus.gif)
Configuring the MicroProfile Rest Client
Invoke the MicroProfile Rest Client with the mpRestClient-1.0 feature.
Before you begin
About this task
The MicroProfile Rest Client builds on the JAX-RS 2.0 Client APIs to provide a type-safe approach to invoke RESTful services over HTTP. You can write client applications with more model-centric code. Complete the following steps to create your own REST clients.
Procedure
- Create an interface that represents the remote service. Match the methods of the interface to
the RESTful APIs of the endpoint. The following example shows a sample interface that accesses a service for online music.
@Path("/playlist") @Consumes("application/json") public interface MusicPlaylistService { @GET List<String> getPlaylistNames(); @GET @Path("/{playlistName}") List<Song> getPlaylist(@PathParam("playlistName") name) throws UnknownPlaylistException; @POST @Path("/{playlistName}") long newPlayList(@PathParam("playlistName") name, List<Song> playlist) throws PlaylistAlreadyExistsException; @PUT @Path("/{playlistName}") long updatePlayList(@PathParam("playlistName") name, List<Song> playlist) throws UnknownPlaylistException; }
Like JAX-RS on the server side, the sample interface uses annotations like @Path, @Consumes, @GET, and @PathParam.
- Invoke methods that are defined in the interface. The sample interface defines methods that you can invoke.
- Invoke the getPlaylistNames method to get the available names of playlists. The REST client implementation sends a GET request to the endpoint at the <baseUrl>/playlist location. This location accepts the application/json media type of a list of strings that indicate the available names of playlists.
- Invoke the getPlaylist method to see which songs are included in a playlist. This method throws an UnknownPlaylistException error, which might also be indicated on the remote service and might return an HTTP 404 response.
- Use a ResponseExceptionMapper command to handle exceptions. The following example converts the HTTP 404 response to a specific
exception.
In the example, both UnknownPlaylistException and PlaylistAlreadyExistsException cases are subclasses of the BasePlaylistException case. The toThrowable response returns an instance of the exception rather than throwing it.@Provider public class PlaylistResponseExceptionMapper implements ResponseExceptionMapper<BasePlaylistException> { @Override public boolean handles(int statusCode, MultivaluedMap<String, Object> headers) { return statusCode == 404 // Not Found || statusCode == 409; // Conflict } @Override public BasePlaylistException toThrowable(Response response) { switch(response.getStatus()) { case 404: return new UnknownPlaylistException(); case 409: return new PlaylistAlreadyExistsException(); } return null; } }
- After you write the interface and response exception mapper, build the implementation and start it. You can build the implementation with either the RestClientBuilder API or Contexts and Dependency Injection (CDI) and MP Config.
- Optional: Use the RestClientBuilder API, which is more
verbose but is useful in environments where CDI is not available, such as in testing.
- Create an instance of the RestClientBuilder API.
- Specify the baseURL URL of the remote endpoint, which is necessary before you build the client.
- Register the response exception mapper. If you need to register other provider classes, such as MessageBodyReaders, MessageBodyWriters, filters, or interceptors, register them with the register method.
- Build the client and pass in the interface class.
- Invoke methods on the client as you would with another Java™ object.
... URL apiUrl = new URL("http://localhost:9080/onlineMusicService"); MusicPlaylistService playlistSvc = RestClientBuilder.newBuilder() .baseUrl(apiUrl) .register(PlaylistResponseExceptionMapper.class) .build(MusicPlaylistService.class); List<String> playlistNames = playlistSvc.getPlaylistNames(); for (String name : playlistNames) { List<Song> songs = playlistSvc.getPlaylist(name); if (hasSongBy(songs, "band name")) { coolPlaylists.add(name); } } ...
- Optional: Use CDI and MP Config to instantiate the client.
- Install the mpRestClient-1.0 feature in the Liberty server.xml file.
- Add either the cdi-1.2 or cdi-2.0 feature.
- Add either the mpConfig-1.1 or mpConfig-1.2 feature.
- Update the MusicPlaylistService interface with the following
annotations:
The @Dependent annotation or another scope annotation, such as @ApplicationScoped or @RequestScoped, is required for CDI to detect and manage the Rest Client interface. The @RegisterRestClient annotation tells the MicroProfile Rest Client implementation to dynamically implement the interface. The @RegisterProvider annotation tells the MicroProfile Rest Client implementation code to register the specified provider class. You can repeat the @RegisterProvider annotation on the same interface for as many providers as you need.@Path("/playlist") @Consumes("application/json") @Dependent @RegisterRestClient @RegisterProvider(PlaylistResponseExceptionMapper.class) public interface MusicPlaylistService { ...
- Inject the client into another managed object. Combine the @Inject annotation
with the @RestClient decorator to tell CDI to inject an instance of the
MusicPlaylistService interface:
@WebServlet(urlPatterns = "/PlaylistServlet") public class PlaylistServlet extends HttpServlet { @Inject @RestClient private MusicPlaylistService playlistService; @Override public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { List<String> names = playlistService.getPlaylistNames(); ...
- Use MP Config to indicate the baseUrl URL of the remote endpoint in the MP
Rest Client implementation. Specify the
<fullyQualifiedInterfaceName>/mp-rest/url configuration property with
MicroProfile Config. One option is to set a system property in the jvm.options
file:
-Dcom.mypkg.MusicPlaylistService/mp-rest/url=http://localhost:9080/onlineMusicService
CDI injection is simpler when you want to bootstrap the client. With MP Config, you can use different URLs for different environments, such as having one URL for test and another URL for production, without needing to change code.
Parent topic: Deploying web services applications to Liberty

File name: twlp_mp_restclient.html