{title:'juneau-rest-client', updated:'8.2.0', updated:'9.0.0'}

##### Maven Dependency

| <dependency> | <groupId>org.apache.juneau</groupId> | <artifactId>juneau-rest-client</artifactId> | <version>{@property juneauVersion}</version> | </dependency>

##### Java Library

| juneau-rest-client-{@property juneauVersion}.jar

##### OSGi Module

| org.apache.juneau.rest.client_{@property juneauVersion}.jar

Built upon the feature-rich Apache HttpClient library, the Juneau RestClient API adds support for fluent-style REST calls and the ability to perform marshalling of POJOs to and from HTTP parts.

##### Example:

| // Create a basic REST client with JSON support and download a bean. | MyBean bean = RestClient.create() | .simpleJson() | .build() | .get(URI) | .run() | .assertStatus().asCode().is(200) | .assertHeader("Content-Type").matchesSimple("application/json*") | .getContent().as(MyBean.class);

Breaking apart the fluent call, we can see the classes being used:

| RestClient.Builder builder = RestClient.create().simpleJson(); | RestClient client = builder.build(); | RestRequest req = client.get(URI); | RestResponse res = req.run(); | RestResponseStatusLineAssertion statusLineAssertion = res.assertStatus(); | FluentIntegerAssertion<RestResponse> codeAssertion = statusLineAssertion.asCode(); | res = codeAssertion.is(200); | FluentStringAssertion<RestResponse> headerAssertion = res.assertHeader("Content-Type"); | res = headerAssertion.matchesSimple("application/json*"); | ResponseContent content = res.getContent(); | MyBean bean = content.as(MyBean.class);

It additionally provides support for creating remote proxy interfaces using REST as the transport medium.

##### Example:

| // Define a Remote proxy for interacting with a REST interface. | @Remote(path="/petstore") | public interface PetStore { | | @RemotePost("/pets") | Pet addPet( | @Content CreatePet pet, | @Header("E-Tag") UUID etag, | @Query("debug") boolean debug | ); | } | | PetStore store = RestClient | .create() | .simpleJson() | .build() | .getRemote(PetStore.class, "http://localhost:10000"); | CreatePet createPet = new CreatePet("Fluffy", 9.99); | Pet pet = store.addPet(createPet, UUID.randomUUID(), true);

The classes are closely tied to Apache HttpClient, yet provide lots of additional functionality:

- {@link oajrc.RestClient} implements {@link org.apache.http.client.HttpClient}, creates {@link oajrc.RestRequest} objects.
- {@link oajrc.RestRequest} implements {@link org.apache.http.client.methods.HttpUriRequest}, creates {@link oajrc.RestResponse} objects.
- {@link oajrc.RestResponse} implements {@link org.apache.http.HttpResponse}, creates {@link oajrc.ResponseContent} and {@link oajrc.ResponseHeader} objects.
- {@link oajrc.ResponseContent} implements {@link org.apache.http.HttpEntity}

Instances of this class are built using the {@link oajrc.RestClient.Builder} class which can be constructed using the {@link oajrc.RestClient#create() RestClient.create()} method as shown above.

Clients are typically created with a root URI so that relative URIs can be used when making requests. This is done using the {@link oajrc.RestClient.Builder#rootUri(Object)} method.

##### Example:

| // Create a client where all URIs are relative to localhost. | RestClient client = RestClient.create().json().rootUri("http://localhost:10000").build(); | | // Use relative paths. | String content = client.get("/subpath").run().getContent().asString();

The {@link oajrc.RestClient} class creates {@link oajrc.RestRequest} objects using the following methods:

- {@link oajrc.RestClient}
  - {@link oajrc.RestClient#get(Object) get(uri)} / {@link oajrc.RestClient#get() get()}
  - {@link oajrc.RestClient#put(Object,Object) put(uri,body)} / {@link oajrc.RestClient#put(Object) put(uri)}
  - {@link oajrc.RestClient#post(Object) post(uri,body)} / {@link oajrc.RestClient#post(Object) post(uri)}
  - {@link oajrc.RestClient#patch(Object,Object) patch(uri,body)} / {@link oajrc.RestClient#patch(Object) patch(uri)}
  - {@link oajrc.RestClient#delete(Object) delete(uri)}
  - {@link oajrc.RestClient#head(Object) head(uri)}
  - {@link oajrc.RestClient#options(Object) options(uri)}
  - {@link oajrc.RestClient#formPost(Object,Object) formPost(uri,body)} / {@link oajrc.RestClient#formPost(Object) formPost(uri)}
  - {@link oajrc.RestClient#formPostPairs(Object,Object...) formPostPairs(uri,parameters...)}
  - {@link oajrc.RestClient#request(String,Object,Object) request(method,uri,body)}

The {@link oajrc.RestRequest} class creates {@link oajrc.RestResponse} objects using the following methods:

- {@link oajrc.RestRequest}
  - {@link oajrc.RestRequest#run() run()}
  - {@link oajrc.RestRequest#complete() complete()}

The distinction between the two methods is that {@link oajrc.RestRequest#complete() complete()} automatically consumes the response body and {@link oajrc.RestRequest#run() run()} does not. Note that you must consume response bodies in order for HTTP connections to be freed up for reuse! The {@link java.io.InputStream InputStreams} returned by the {@link oajrc.ResponseContent} object are auto-closing once they are exhausted, so it is often not necessary to explicitly close them.

The following examples show the distinction between the two calls:

| // Consuming the response, so use run(). | String content = client.get(URI).run().getContent().asString(); | | // Only interested in response status code, so use complete(). | int status = client.get(URI).complete().getStatusCode();