Java RESTful Services Client
3.1
3.0
2.1
2.0

This feature enables support for Java Client API for JAX-RS 2.1.

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 client functions by enabling the RESTful Web Services Client 3.0 feature. The JAX-RS 2.0 and 2.1 client implementations are available through the Java RESTful Services Client feature (jaxrsClient-2.0 and jaxrsClient-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 Java Restful Services (JAX-RS) and Jakarta RESTful Web Services 3.0.

Enabling this feature

To enable the Java RESTful Services Client 2.1 feature, add the following element declaration into your server.xml file, inside the featureManager element:

<feature>jaxrsClient-2.1</feature>

Examples

With the JAX-RS Client APIs, you can specify properties on the client that configure settings like timeouts, proxy hosts, and SSL properties. You can set these properties in the Java code or in the server configuration. The following examples show how you can set webTarget values in the server.xml so that you can change them without the need to edit and recompile the Java code.

Change settings when an application moves from development to production environments

If the application is deployed in a different environment, certain settings might need to change. For example, an application might initially be written to run in a development environment, where all remote RESTful services are available without a proxy server and can connect quickly:

public Widget getRemoteWidget(String id) {
    Client client = ClientBuilder.newClient();
    WebTarget target = client.target("https://somehost:9443/WidgetStore/widgets/");
    Widget widget = target.path(id).request().get(Widget.class);
    return widget;
}

However, when this application is deployed in a production environment it might be necessary to add new settings because remote RESTful services might need a proxy server to establish connections. You can specify new settings by adding the following configuration to your server.xml file:

<webTarget uri="https://somehost:9443/WidgetStore*" proxyHost="myProxyHost" proxyPort="55555" proxyType="HTTP"
           connectionTimeout="60000" receiveTimeout="60000" />

This configuration alters the webTarget element in the Java code to use the proxyHost and proxyPort attributes to specify the values for a HTTP proxy server. The connectionTimeout and receiveTimeout attributes are used to set connection and receive timeouts of 60 seconds (60,000 milliseconds) instead of the default timeouts.

Modify SSL configuration in development

During development, an SSL certificate might not match the server hostname that tests the application because it matches the server hostname that deploys the application in production. The configuration can be changed during development to use a different SSL configuration or to disable hostname verification of SSL certificates:

<webTarget uri="https://somehost:9443/WidgetStore*" sslConfig="mySSLRef" disableCNCheck="true" />

To maintain application security, you do not disable SSL verification in production environments.

Set custom properties

If your application uses providers such as the ClientRequestFilter or ClientResponseFilter interfaces, they can read and react to custom properties that are set on the JAX-RS Client or the WebTarget interface. You can also change the Open Liberty client implementation behavior by setting custom properties. These properties can be set programmatically by using the webTarget.property("myCustomProperty", "someValue") configuration but you can also set custom properties by specifying the WebTarget element in your server.xml file:

<webTarget uri="https://somehost:9443/WidgetStore*" myCustomProperty="prod" />

For a complete list of pre-defined properties, see webTarget.

Enable MicroProfile JWT authentication for JAX-RS services

If you add the JAX-RS Client feature to your server configuration along with the MicroProfile JSON Web Token feature, you can use MicroProfile JWT to authenticate JAX-RS services. With the Open Liberty JAX-RS client, you can use MicroProfile JWT as an authentication method for JAX-RS services, as shown in the following example:

<webTarget uri="http://localhost:56789/protectedResourceWithMPJWT*" authnToken="mpjwt" />

The authnToken attribute in the webTarget element adds MicroProfile JWT as an authorization header when the JAX-RS service that is specified by the http://localhost:56789/protectedResourceWithMPJWT* endpoint URL in the uri attribute is called.

Feature configuration elements

Standard API packages provided by this feature

  • javax.activation

  • javax.ws.rs

  • javax.ws.rs.client

  • javax.ws.rs.container

  • javax.ws.rs.core

  • javax.ws.rs.ext

  • javax.ws.rs.sse

  • javax.xml.bind

  • javax.xml.bind.annotation

  • javax.xml.bind.annotation.adapters

  • javax.xml.bind.attachment

  • javax.xml.bind.helpers

  • javax.xml.bind.util

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

  • JavaSE-23.0

Platform Versions

  • javaee-8.0

Features that enable this feature

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.

com.ibm.websphere.appserver.jaxrsClient-2.1; type="osgi.subsystem.feature"

SPI packages provided by this feature