{title:'REST Overview', created:'9.0.0'}
REST Server/Client APIs

The {@doc juneau-rest-server juneau-rest-server} and {@doc juneau-rest-client 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 PetStore { | | @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. | 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 PetStoreService { | | @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 Simple JSON support and BASIC auth. | RestClient client = RestClient.create().simpleJson().basicAuth(...).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 | 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.