The JAX-RS client API encapsulates the uniform interface constraint, which is a key constraint of the REST architectural style, and offers many convenient APIs for accessing the web resources. We will start by looking at the JAX-RS client API for reading a simple RESTful web service.

You will use the javax.ws.rs.client.ClientBuilder factory class as the entry point to the client API. The javax.ws.rs.client.Client instance returned by ClientBuilder exposes a set of high-level APIs for accessing the web resources.

Let's now apply what we've learned and see how we can access the REST resource identified by the following URI: http://localhost:8080/rest-chapter3-service/webresources/departments.

The preceding URI has the following two parts:

• Base URI: http://localhost:8080/rest-chapter3-service/webresources
• URI path fragments that identify the REST resource: /departments

We will build WebTarget pointing to the base URI as follows:

import javax.ws.rs.client.Client; 
import javax.ws.rs.client.ClientBuilder;  
import javax.ws.rs.client.WebTarget; 
 
Client client = javax.ws.rs.client.ClientBuilder.newClient(); 
String BASE_URI =  
  "http://localhost:8080/rest-chapter3-service/webresources"; 
//Builds a web resource target pointing to BASE_URI  
WebTarget  webTarget = client.target(BASE_URI); 

You can append /departments to the base web target instance in order to complete the URI for the REST API, which returns the JSON representation of the department objects. You can do this by calling path(String path) on the WebTarget instance as follows:

webTarget.path("departments"); 

This call creates a new WebTarget instance by appending the input path to the URI of the current target instance.

Once you have a WebTarget instance pointing to a valid REST resource, you can start building a request to the targeted REST API by calling the request() method. In the request method, you can specify the desired media types for the response, such as text/html, text/plain, text/xml, and application/json:

The request() method returns the javax.ws.rs.client.Invocation.Builder object, which can be used for building the appropriate innovation handlers. The last step in this process is to invoke the request and get a response.

The following code snippet illustrates all the steps that we discussed till now for calling the REST APIs:

Client client = javax.ws.rs.client.ClientBuilder.newClient(); 
String BASE_URI =  
  "http://localhost:8080/rest-chapter3-service/webresources"; 
WebTarget  webTarget = client.target(BASE_URI); 
//Append departments URI path to Base URI 
WebTarget resource = webTarget.path("departments"); 
 
// Build appropriate request type by specifying the content 
// type for the response 
Builder builder=resource. 
  request(javax.ws.rs.core.MediaType.APPLICATION_JSON);  
//Build a GET request invocation 
Invocation invocation=builder.buildGet();  
//Invoke the request and receive the response in  
// specified format type. 
GenericType responseType=new GenericType<List<Department>>() { }; 
List<Department> depts = invocation.invoke(responseType); 

While calling the invoke(Class<T> responseType) method on the Invocation object, you can specify the desired response Java type as the input. The runtime will automatically convert the response message content into the desired Java type.