JAX-RS 2.1 API Specification

The Java API for RESTful Web Services provides portable APIs for developing, exposing and accessing Web applications designed and implemented in compliance with principles of REST architectural style.

Web resources

JAX-RS core APIs enable developers to rapidly build Web applications in Java that are characteristic of the best designed parts of the Web. The API brings in support for designing and implementing Web resources and application that follow principles of REST (Representational State Transfer) architectural style to the Java Platform.

In JAX-RS, Java POJOs can be exposed as RESTful Web resources independent of the underlying technology using a high level easy-to-use declarative annotation-based API. E.g.:

@Path("widgets/{widgetid}")
@Consumes("application/widgets+xml")
@Produces("application/widgets+xml")
public class WidgetResource {

    @GET
    public String getWidget(@PathParam("widgetid") String id) {
        return getWidgetAsXml(id);
    }

    @PUT
    public void updateWidget(@PathParam("widgetid") String id,
                             Source update) {
       updateWidgetFromXml(id, update);
    }

    ...
}

Web resource clients

JAX-RS client API is a Java based API used to access resources on the Web. It is not restricted to resources implemented using JAX-RS. It provides a higher-level abstraction compared to a plain HTTP communication API as well as integration with the JAX-RS extension providers, in order to enable concise and efficient implementation of reusable client-side solutions that leverage existing and well established client-side implementations of HTTP-based communication.

The JAX-RS Client API also encapsulates the Uniform Interface Constraint – a key constraint of the REST architectural style – and associated data elements as client-side Java artifacts and supports a pluggable architecture by defining multiple extension points.

Following example demonstrates a simple JAX-RS client API usage scenario:

    Client client = ClientBuilder.newClient();

    client.property("MyProperty", "MyValue")
          .register(MyProvider.class)
          .enable(MyFeature.class);

    Response res = client.target("http://example.org/hello").request("text/plain").get();
    String message = res.readEntity(String.class);
 

Provider extensions

JAX-RS applications may provide custom extensions to the client and server runtime using the common extension APIs defined in javax.ws.rs.ext package, namely entity providers and entity provider interceptors. Additionally, request and response processing chains on client as well as server side can be further customized by implemening custom request and response filters - see the ClientRequestFilter, ClientResponseFilter, ContainerRequestFilter, ContainerResponseFilter APIs.