Eclipse MicroProfile Rest Client API
Payara Platform 6.2023.7 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 |
---|---|---|
|
|
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 |
---|---|---|
|
|
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
See Also
-
{repo}/spec/src/main/asciidoc/clientexamples.asciidoc[MicroProfile Rest Client Examples]
-
{repo}/spec/src/main/asciidoc/cdi.asciidoc[MicroProfile Rest Client CDI Integration]
-
{repo}/spec/src/main/asciidoc/async.asciidoc[MicroProfile Rest Client Asynchronous Configuration]
-
{repo}/spec/src/main/asciidoc/providers.asciidoc[MicroProfile Rest Client JAX-RS Providers]
-
{repo}/spec/src/main/asciidoc/ssl.asciidoc[MicroProfile Rest Client SSL Configuration Specifics]