Eclipse MicroProfile Rest Client API

Since Payara Server 4.1.2.182 and 5.182

Provided version of the API: MicroProfile Rest Client 1.4

Background

The MicroProfile Rest Client provides a type-safe approach to invoke RESTful services over HTTP. An 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 Eclipse MicroProfile Rest Client repository contains a number of examples and information about how to use this API.

Implementation in Payara is based on Jersey’s Microprofile Rest client, the interaction with client interfaces is translated into interaction with standard JAX-RS client.

CDI

Full MicroProfile documentation available here

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 case must either be configured directly in attribute baseUri of @RegisterRestClient or via Microprofile Config properties.

Async

Full MicroProfile documentation available here

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 client communication occurs on another thread.

The threadpool to use is configured via RestClientBuilder.executorService, or default one is used, which is managed thread pool of the server.

Providers

Full MicroProfile documentation available here

The RestClientBuilder interface extends the Configurable interface from JAX-RS, allowing a user to register custom providers while it’s being built. Payara Server and Micro support the following provider types:

  • ClientRequestFilter

  • ClientResponseFilter

  • MessageBodyReader

  • MessageBodyWriter

  • ParamConverter

  • ReaderInterceptor

  • WriterInterceptor

  • ResponseExceptionMapper

See the full MicroProfile documentation for the registration methods.

SSL

Full MicroProfile documentation available here

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

  • Trust store, listing trusted certificates and authorities — by default the one used by the Payara Platform is used

  • Hostname verifier, useful for suppressing trust checks for some host names

  • Keystore for setting up mutual SSL trust

Programmatically it is also possible to provide an implementation of SslContext to control all aspects of SSL communication.

SSL Context configuration

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

  • Adding the property during the Rest Client call

Property Payara Public API constant

Description

fish.payara.rest.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

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

  • Adding with MicroProfile Config

Property Payara Public API constant Description

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 applicaitons. 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 keystore.

Proxy Configuration

MicroProfile Rest Client 2.0 introduced support for configuring proxy servers via MicroProfile Config and the RestClientBuilder API. On a vanilla install however, Payara Platform will not utilise these settings and the proxy will be ignored. This is due to Jersey, the JAX-RS client and underlying implementation of MicroProfile Rest Client of Payara Platform, not by default supporting configuration of proxies on a per-client basis (only via the global JVM system property). Jersey does however support 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 of MicroProfile Rest Client, you must perform a number of steps to configure Payara to make use of one of these connectors. Below are instructions for how to configure Payara Server to make use of Apache HTTP Client.

Create a RestClientListener

To configure Jersey to use Apache HTTP Client as its connector, a RestClientListener can be used to register the connector for each new client. You can add one to your application as described by Provider Declaration section of the MicroProfile Rest Client specification.

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 Payara Server:

  • 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

Again, please refer to the Payara BOM artefact for the specific version of the Jersey connector to use.