Home
  • Dec 11, 2018

JAX-RS Client API

This post explains what is JAX-RS Client API and how to use it via Jersey Client API. We will talk about the Maven dependencies, Client, WebTarget, and HTTP response.

Overview

Java™ API for RESTful Web Services (JAX-RS) provides Client API for accessing web resources. In this article, we will talk about the basic concepts of the Client API. After reading, you will understand:

  • Maven dependencies when using Jersey as JAX-RS client
  • Create a Client instance
  • Create a WebTarget instance
  • Consume a HTTP response

The Java classes introduced in this article are principally defined in package javax.ws.rs.client. I’m using Jersey, the reference implementation of JAX-RS for the examples.

Maven Dependencies

In order to use Jersey as JAX-RS client, you need to add the following dependency in your POM (pom.xml):

<dependency>
  <groupId>org.glassfish.jersey.core</groupId>
  <artifactId>jersey-client</artifactId>
  <version>2.27</version>
</dependency>

Create Client Instance

An instance of Client is required to access a Web resource using the Client API. The default instance of Client can be obtained by calling newClient on ClientBuilder. Client instances can be configured using methods inherited from Configurable as follows:

// Create instance
Client client = ClientBuilder.newClient();

// Configure instance
client.property("MyKey", "MyValue")
      .register(MyProvider.class);

Create WebTarget Instance

Using any Client#target(...) method can create a WebTarget from Client. They accept String, URI, URI Builder, and Link as input parameter type. For example, create web target using a String:

WebTarget books = client.target("http://localhost:8080/books");

Once created, you can use path to define the path to a specific resource. For example, if you need to request book 1 defined by the following URL:

http://localhost:8080/books/1

You can do:

books.path("1");

Conceptually, the steps required to submit a request are the following: 1. obtain an instance of Client; 2. create a WebTarget; 3. create a request from the WebTarget; 4. submit a request or get a prepared Invocation for later submission. JAX-RS uses method chaining to support different configurations, such as setting headers, cookies, query parameters, etc.

Response r = client.target("http://example.org/api")
  .queryParam("myParam", "v")
  .request("text/plain")
  .header("myHeader", "v")
  .get();

Consume HTTP Response

Once the HTTP response is obtained as class javax.ws.rs.core.Response, you can get the HTTP status, read the entity, get the MIME type, cookie, etc.

Response response = target.path("1").request().get();

response.getStatus();
// out: 200

response.readEntity(String.class);
// out: {"id":1,"name":"Awesome"}

Conclusion

In this article, we’ve seen how to create a Client and WebTarget using Jersey Client API, in particular the method chaining techniques for setting different parts of a HTTP request. We’ve also seen how to get information from the HTTP response. Hope you enjoy this article, see you the next time!

References

Search