{8.2.0-updated} REST Proxies

One of the more powerful features of the REST client class is the ability to produce Java interface proxies against arbitrary 3rd party REST resources.

The methods to retrieve remote interfaces are:

- {@link oajr.client2.RestClient}
  - {@link oajr.client2.RestClient#getRemote(Class) getRemote(Class<T>)} returns T
  - {@link oajr.client2.RestClient#getRemote(Class,Object) getRemote(Class<T>,Object)} returns T
  - {@link oajr.client2.RestClient#getRemote(Class,Object,Serializer,Parser) getRemote(Class<T>,Object,Serializer,Parser)} returns T

Annotations are used on the interface and interface methods to specify how to convert input and output to HTTP headers, query parameters, form post parameters, or request/response bodies.

- {@link oaj.http.remote}
  - {@link oaj.http.remote.Remote} - Applied to interface class.
  - {@link oaj.http.remote.RemoteMethod} - Applied to interface methods.
- {@link oaj.http.annotation}
  - {@link oaj.http.annotation.Body}
  - {@link oaj.http.annotation.Header}
  - {@link oaj.http.annotation.FormData}
  - {@link oaj.http.annotation.Query}
  - {@link oaj.http.annotation.Path}
  - {@link oaj.http.annotation.Request}
  - {@link oaj.http.annotation.Response}

##### Example:

@Remote(path="/petstore") public interface PetStore { @RemoteMethod(method=POST, path="/pets") Pet addPet( @Body CreatePet createPet, @Header("E-Tag") UUID etag, @Query("debug") boolean debug ); }

// Use a RestClient with default Simple JSON support. RestClient client = RestClient.create().simpleJson().build(); // Instantiate our proxy interface. PetStore store = client.getRemote(PetStore.class, "http://localhost:10000"); // Use it to create a pet. CreatePet createPet = new CreatePet("Fluffy", 9.99); Pet pet = store.addPet(createPet, UUID.randomUUID(), true);

The call above translates to the following REST call:

POST http://localhost:10000/petstore/pets?debug=true HTTP/1.1 Accept: application/json Content-Type: application/json E-Tag: 475588d4-0b27-4f56-9296-cc683251d314 { name: 'Fluffy', price: 9.99 }

The @RemoteMethod annotations can be eliminated if you use specific naming conventions on your method names to identify the HTTP method and path.

##### Example:

@Remote(path="/petstore") public interface PetStore { // @RemoteMethod optional since method and path is inferred from method name. String postPets(@Body CreatePet pet); }