Jakarta RESTful Web Services
3.1
3.0
2.1
2.0

This feature enables support for Jakarta RESTful Web Services 3.0. These annotations can be used to define web service clients and endpoints that comply with the REST architectural style. Endpoints are accessed through a common interface that is based on the HTTP standard methods.

Jakarta RESTful Web Services, formerly known as JAX-RS, is a Jakarta EE platform API. In Open Liberty 21.0.0.12 and later, you can use Jakarta RESTful Web Services 3.0 functions by enabling the RESTful Web Services 3.0 feature. The JAX-RS 2.0 and 2.1 implementations are available through the Java RESTful Services feature (jaxrs-2.0 and jaxrs-2.1). The change in feature name and version reflects the change in API package name prefixes from javax.* to jakarta.*, which is common to all Jakarta EE 9.1 features. For more information, see Differences between Jakarta RESTful Web Services 3.0 and Java Restful Services (JAX-RS).

If you are updating your application from using the restfulWS-3.0 feature to using the restfulWS-3.1 feature, changes in API behavior might require you to update your application code. For more information, see Differences between Jakarta RESTful Web Services 3.1 and 3.0.

In Jakarta Restful Web Services 3.0 and earlier, support for sending and receiving multipart/form-data parts was provided by the Liberty-specific IAttachment and IMultipartBody APIs, which are deprecated in version 3.1, which is included in Liberty 23.0.0.3. In this version and later, this support is provided by the EntityPart API that is defined in the RESTful Web Services specification. For more information, see section 3.5.2 of the Jakarta Restful Web Services specification.

Enabling this feature

To enable the Jakarta RESTful Web Services 3.0 feature, add the following element declaration into your server.xml file, inside the featureManager element:

<feature>restfulWS-3.0</feature>

Examples

Access security details with a context object

In RESTful Web Services applications, you can use annotations to add dependency injections of context objects that access information from HTTP requests. Context objects can provide information that is associated with the application such as the specific HTTP request or response, or the application environment. In the following example, the @Context annotation injects the SecurityContext context object in the Jakarta API that provides access to security details, such as user credentials:

@Context
SecurityContext sec;

@GET
@Path("/getGroups")
public Set<String> getGroups() {
       Set<String> groups = null;
       Principal user = sec.getUserPrincipal();
       if (user instanceof JsonWebToken) {
                JsonWebToken jwt = (JsonWebToken) user;
                groups= = jwt.getGroups();
       }
       return groups;
}

To access security details, the SecurityContext context object uses the sec.getUserPrincipal() method that determines the identity of the user that makes the HTTP request. The if statement specifies the JSONWebToken claims that identify the user.

Inject the MicroProfile JWT interface to access application resources

You can inject interfaces in RESTful Web Services applications to access resources, such as user details. In the following example, the @Inject annotation injects the JsonWebToken interface in the Jakarta API to obtain the jwtPrincipal object that contains details from the MicroProfile JWT that identifies the user:

@RequestScoped
public class JwtEndpoint {
       @Inject
       private JsonWebToken jwtPrincipal;
       @GET
       @Path("/getInjectedPrincipal")
       public String getInjectedJWT() {
          return  this.jwtPrincipal.getName();
       }
}

Liberty API packages provided by this feature

Features that this feature enables

Supported Java versions

  • JavaSE-1.8

  • JavaSE-11.0

  • JavaSE-17.0

  • JavaSE-21.0

Developing a feature that depends on this feature

If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content header in your feature manifest file.

io.openliberty.restfulWS-3.0; type="osgi.subsystem.feature"