Jakarta RESTful Web Services 2.1 API Specification

Jakarta RESTful Web Services provides a foundational API to develop web services following the Representational State Transfer (REST) architectural pattern. This API is distributed under the Eclipse Foundation Specification License.

Web resources

The 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.

With this API, 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

The Client API is a Java based API used to access resources on the Web. It is not restricted to resources implemented using the Server API. It provides a higher-level abstraction compared to a plain HTTP communication API as well as integration with the API 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 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 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

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.