Skip to main content

juneau-rest

The juneau-rest family of modules provides a complete, end-to-end REST stack built on top of the Juneau marshalling APIs. Because both the server and client sides share the same POJO-centric marshalling layer, you can create sophisticated Java-based REST communications layers that completely hide away the complexities of the REST protocol.

REST Module Family​

Which client?

juneau-rest-client (org.apache.juneau.rest.client.RestClient) is the recommended REST client. It is generally available in 10.0.0, transport-agnostic, and uses the JDK HttpClient by default. juneau-rest-client-classic (org.apache.juneau.rest.client.classic.RestClient, Apache HttpClient 4.5) stays supported and is not deprecated; it is the stable choice for existing users. See Choosing a REST Client.

  • juneau-rest-common — Shared HTTP artifacts (headers, parts, entities, responses, annotations, and remote-proxy interfaces) used by both the server and client sides.
  • juneau-rest-server — Wrap POJOs and expose them as full-fledged REST resources in any servlet container using a bare-minimum amount of code.
  • juneau-rest-client — The recommended REST client: transport-agnostic (JDK HttpClient by default), with automatic marshalling of POJOs to and from HTTP parts, plus remote-proxy interface support. Generally available in 10.0.0.
  • juneau-rest-client-classic — The Apache HttpClient 4.5–based client from 9.x. Stable and supported (not deprecated) for existing users.
  • juneau-rest-mock — Serverless in-JVM testing of @Rest- and @Remote-annotated classes that performs real serialization/parsing while bypassing the network layer.
  • juneau-rest-server-springboot — Spring Boot integration allowing REST resources and framework beans to be defined as injectable Spring beans.
  • juneau-rest-server-mcp — Model Context Protocol support for exposing REST resources to AI tooling.
  • juneau-rest-client-mcp — Model Context Protocol client support for consuming MCP servers (including Juneau's own).

End-to-End Example​

The juneau-rest-server and juneau-rest-client libraries can be used by themselves, or together to create simplified yet sophisticated REST communications layers.

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 200-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, a REST client is used to construct a remote proxy to our REST service. This example uses the classic RestClient class (juneau-rest-client-classic), which has a built-in BASIC auth shortcut. The recommended juneau-rest-client builds the same proxy with client.remote(PetStoreClient.class); see NG Remote Proxies.

// juneau-rest-client-classic (org.apache.juneau.rest.client.classic.RestClient)
// Use a classic 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 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.