Jakarta RESTful Web Services 3.0 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

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

Packages 
Package Description
jakarta.ws.rs
High-level interfaces and annotations used to create RESTful service resources.
jakarta.ws.rs.client
The JAX-RS client API
jakarta.ws.rs.container
Container-specific JAX-RS API.
jakarta.ws.rs.core
Low-level interfaces and annotations used to create RESTful service resources.
jakarta.ws.rs.ext
APIs that provide extensions to the types supported by the JAX-RS API.
jakarta.ws.rs.sse
Server-Sent Events related API.