Eclipse MicroProfile Rest Client API

Payara Platform 7.2024.1.Alpha3 provides MicroProfile Rest Client 3.0.1

Background

The MicroProfile Rest Client provides a type-safe approach to invoke RESTful services over HTTP. The aim of this specification is to provide a much more natural coding style, with the underlying MicroProfile implementation handling the communication between the client and service.

The complete specification can be found on the Eclipse MicroProfile website.

Breaking changes introduced in MicroProfile Rest Client 3.0.1 are listed in the official specification under Release Notes for MicroProfile Rest Client 3.0.1

The Payara Platform implementation of this specification is based on Jersey’s MicroProfile Rest client, the interaction with client interfaces is translated into interaction with standard JAX-RS clients.

Jakarta CDI

Rest Client interfaces may be injected as CDI beans. To do this, you must first register your interface class by using the @RegisterRestClient annotation, and then use the @RestClient qualifier on the injected bean, like so:

@RegisterRestClient
public interface MyServiceClient {
    @GET
    @Path("/greet")
    Response greet();
}

@ApplicationScoped
public class MyService {
    @Inject
    @RestClient
    private MyServiceClient client;
}

The endpoint to connect to in such a case must either be configured directly in attribute baseUri of the @RegisterRestClient annotation or via Microprofile Configuration properties.

Asynchronous Communication

It is possible for Rest Client interface methods to be declared asynchronous, by having return type of CompletionStage<?>. This allows the thread invoking the interface method to proceed while the effective client communication occurs on another thread.

The thread pool used in this call can be configured via the RestClientBuilder.executorService method. If this setting is not configured, a default, server-managed thread pool will be provided.

Providers

The RestClientBuilder interface extends the Configurable interface of the JAX-RS API, allowing users to register custom providers while at the object’s instantiation. The following provider types are supported:

ClientRequestFilter
ClientResponseFilter
MessageBodyReader
MessageBodyWriter
ParamConverter
ReaderInterceptor
WriterInterceptor
ResponseExceptionMapper

See the full documentation (linked below) for more information on available registration methods.

SSL Configuration

On a per-client basis, or via Microprofile Configuration properties, the following aspects of secure client communication can be set:

Truststore, listing trusted certificates and authorities — by default the one used by the Payara Platform is used
Keystore for setting up mutual SSL trust
Hostname verifier, useful for suppressing validity checks for whitelisted host names

Programmatically it is also possible to provide an implementation of the javax.net.ssl.SSLContext class to have major control over all aspects of this secure communication channel.

SSL Context configuration

You can define the certificate alias rest client will use with one of the following approaches:

During REST client call

Property Public API Constant Description

Property	Public API Constant	Description
`fish.payara.jaxrs.client.certificate.alias`	`PayaraConstants.REST_CLIENT_CERTIFICATE_ALIAS`	The alias name of the certificate

fish.payara.jaxrs.client.certificate.alias

PayaraConstants.REST_CLIENT_CERTIFICATE_ALIAS

The alias name of the certificate

The name of the property is defined as a constant in the fish.payara.security.client.PayaraConstants class.

Example

Here’s an example of how to set up the property when executing a new MP Rest Client call:

public class Component{
    public void executeRestClientCall(){
        RestClientBuilder.newBuilder()
                        .baseUri(new URI("https://localhost:8080/service"))
                        .property(PayaraConstants.REST_CLIENT_CERTIFICATE_ALIAS, "someAliasName")
                        .build(Service.class);
    }
}

On MicroProfile Configuration

Property Public API Constant Description

Property	Public API Constant	Description
`payara.certificate.alias`	`PayaraConstants.MP_CONFIG_CLIENT_CERTIFICATE_ALIAS`	The alias name of the certificate

payara.certificate.alias

PayaraConstants.MP_CONFIG_CLIENT_CERTIFICATE_ALIAS

The alias name of the certificate

You can define the alias globally as a MicroProfile Config property, either in an application-specific config source only for a single application, or with a global config source for all applications. In this case you don’t need to add it during every single Rest Client call.

For this to work, you need to include the certificate with the given alias in the default Payara Server keystore.

Proxy Configuration

MicroProfile Rest Client 2.0 introduced support for configuring proxy servers via MicroProfile Config properties and the RestClientBuilder API. On a vanilla installation however, Payara Platform will not use these settings thus they will be ignored. This is due to Jersey, the JAX-RS client and underlying implementation of MicroProfile Rest Client, which by default, doesn’t support the configuration of proxies on a per-client basis (only via a global JVM-level system property).

However, Jersey supports proxy configuration on a per-client basis when using non-default "connectors" (the means by which Jersey performs the actual network call)

If you wish to make use of this feature, you must perform a number of steps to configure Payara Server to use of one of these non-default Jersey connectors.

Below are instructions for how to configure Payara Server to make use of Apache HTTP Client connector.

Create a RestClientListener

To configure Jersey to use Apache HTTP Client as its connector, a RestClientListener must be used to register the connector for each new client. You can add one to your application by simply registering as a custom JAX-RS provider.

Below is a simple example of registering the Jersey Apache HTTP Client Connector:

public class RestClientApacheHttpClientListener implements RestClientListener {

    @Override
    public void onNewClient(Class<?> aClass, RestClientBuilder restClientBuilder) {
        restClientBuilder.register(new ApacheConnectorProvider());
    }
}

The ApacheConnectorProvider class can be found in the org.glassfish.jersey.connectors:jersey-apache-connector library, please refer to the Payara BOM artefact for the specific version of the Jersey connector to use.

Add Apache HTTP Client Dependencies

In addition to the above, you will also need to add the following dependencies to the Payara Server domain (if applicable):

org.apache.httpcomponents:httpclient-osgi:4.5.13
org.apache.httpcomponents:httpcore-osgi:4.4.14
commons-logging:commons-logging:1.2

These can be included with your application or added to the server via the add-library command:

asadmin add-library httpclient-osgi-4.5.13.jar httpcore-osgi-4.4.14.jar commons-logging-1.2.jar

If you haven’t bundled the library in your application, you will also need to add the org.glassfish.jersey.connectors:jersey-apache-connector dependency to Payara Server:

asadmin add-library jersey-apache-connector-${jersey.version}.jar