Eclipse MicroProfile Rest Client API

Since Payara Server 4.1.2.182 and 5.182

Provided version of the API: MicroProfile Rest Client 1.3

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.