{title:'REST Proxies', created:'8.2.0', updated:'9.0.0'}

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 oajrc.RestClient}
  - {@link oajrc.RestClient#getRemote(Class) getRemote(Class<T>)} returns T
  - {@link oajrc.RestClient#getRemote(Class,Object) getRemote(Class<T>,Object)} returns T
  - {@link oajrc.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.RemoteOp} - Applied to interface methods.
- {@link oaj.http.annotation}
  - {@link oaj.http.annotation.Content}
  - {@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 { | | @RemotePost("/pets") | Pet addPet( | @Content 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 @RemoteOp 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 { | | // @RemoteOp optional since method and path is inferred from method name. | String postPets(@Content CreatePet pet); | }