Getting Started with the Apache Wink Client

The following section details the getting started examples that demonstrate how to write a simple client that consume RESTful Web Services with the Apache Wink Client.

GET Request

The following example demonstrates how to issue an Http GET request.

// create the rest client instance
1  RestClient client = new RestClient();

// create the resource instance to interact with
2  Resource resource = client.resource("http://services.com/HelloWorld");
// perform a GET on the resource. The resource will be returned as plain text
3  String response = resource.accept("text/plain").get(String.class);

Explanation

The RestClient is the entry point for building a RESTful Web Service client. In order to start working with the Wink Client, a new instance of RestClient needs to be created, as the example shows in line 1 of the example. A new Resource is then created with the given URI, by calling the RestClient#resource() method as appears in line 2.

Finally, the Resource#get() method is invoked in order to issue an Http GET request as appears in line 3.
Once the Http response is returned, the client invokes the relevant provider to desterilizes the response in line 3.

POST Request

The following example demonstrates how to issue an Http POST request.

// create the rest client instance
1  RestClient client = new RestClient();

// create the resource instance to interact with
2  Resource resource = client.resource("http://services.co");

// issue the request
3  String response = resource.contentType("text/plain").accept("text/plain").post(String.class, "foo");

Explanation

The POST Request example demonstrates how to issue a simple Http POST request that sends and receives resources as strings.

First, a new instance of a Resource is created through the RestClient. The Http POST request is then issued by specifying the request and response media types and the response entity type (String.class).

POST Atom Request

The following example demonstrates how to issue an Http POST request that sends and receives atom entries.

// create the rest client instance
1  RestClient client = new RestClient();

// create the resource instance to interact with
2  Resource resource = client.resource("http://services.co");

3  AtomEntry request = getAtomEntry();

// issue the request
4  AtomEntry response = resource.contentType("application/atom+xml").accept("application/atom+xml").post(AtomEntry.class, request);

Explanation

The Apache Wink Client provides an object model for Atom (atom feed and atom entry), and supplies out-of-the-box providers that enable sending and receiving atom feeds and entries.

Using ClientResponse

The following example demonstrates how to use the ClientResponse object in order to de-serialize the response entity.

// create the rest client instance
1  RestClient client = new RestClient();

// create the resource instance to interact with
2  Resource resource = client.resource("http://services.co");

// issue the request
3  ClientResponse response = resource.accept("text/plain").get();

// deserialize response
4  String responseAsString = response.getEntity(String.class);

Explanation

If the response entity type is not provided when invoking the Resource#get() method that appears in line 3, the response will be returned as the raw ClientResponse. In order to trigger the response deserialization mechanism, the ClientResponse#getEntity() method needs to be invoked as it appears in line 4 with the required response entity type.