{title:'End-to-End REST', created:'9.0.0'}

The juneau-rest-server and juneau-rest-client libraries provide server and client side REST capabilities that can be used by themselves, or together to create simplified yet sophisticated Java-based REST communications layers that completely hide away the complexities of the REST protocol.

A typical pattern is to define a REST API on the server side:

| @Rest(path="/petstore") | public class PetStoreRest { | | @RestPost(path="/pets", guards=AdminGuard.class) | public Ok addPet( | @Content CreatePet createPetBean, | @Header("E-Tag") UUID etag, | @Query("debug") boolean debug | ) throws BadRequest, Unauthorized, InternalServerError { | // Process request here. | return Ok.OK; // Standard 400-OK response. | } | }

Then define a Java interface that can be provided to consumers of your API to access your REST API:

| @Remote(path="/petstore") | public interface PetStoreClient { | | @RemotePost("/pets") | Ok addPet( | @Content CreatePet createPet, | @Header("E-Tag") UUID etag, | @Query("debug") boolean debug | ) throws BadRequest, Unauthorized, InternalServerError; | }

Note that you may choose to have your service class implement your interface. The REST libraries will happily look for annotations defined on methods of parent classes and interfaces. It's up to you how you want to design it.

Finally, the {@link oajrc.RestClient} class is used to construct a remote proxy to our REST service:

| // Use a RestClient with default JSON 5 support and BASIC auth. | RestClient client = RestClient.create().json5().basicAuth(...).build(); | | // Instantiate our proxy interface. | PetStoreClient store = client.getRemote(PetStoreClient.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 | Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== | E-Tag: 475588d4-0b27-4f56-9296-cc683251d314 | | { | name: 'Fluffy', | price: 9.99 | }

It looks simplistic but the server and client APIs are highly sophisticated libraries that allow you to perform complex tasks using very little code.