Chapter 51. MicroProfile Rest Client

Whenever no media type is specified by, for example, @Consumes or @Produces annotations, the media type of a request entity or response entity is "application/json". This is different than Jakarta RESTful Web Services, where the media type defaults to "application/octet-stream".

In addition to programmatic registration of providers as illustrated above, it is also possible to register providers declaratively with annotations introduced in MicroProfile Rest Client. In particular, providers can be registered by adding the org.eclipse.microprofile.rest.client.annotation.RegisterProvider annotation to the target interface:

@Path("resource")
@RegisterProvider(MyClientResponseFilter.class)
@RegisterProvider(MyMessageBodyReader.class)
public interface TestResourceIntf2 {

   @Path("test/{path}")
   @Consumes("text/plain")
   @Produces("text/html")
   @POST
   public String test(@PathParam("path") String path, @QueryParam("query") String query, String entity);
}

Declaring MyClientResponseFilter and MyMessageBodyReader with annotations eliminates the need to call RestClientBuilder.register().

One more way to register providers is by implementing one or both of the listeners in package org.eclipse.microprofile.rest.client.spi:

public interface RestClientBuilderListener {

    void onNewBuilder(RestClientBuilder builder);
}

public interface RestClientListener {

    void onNewClient(Class<?> serviceInterface, RestClientBuilder builder);
}

which can access a RestClientBuilder upon creation of a new RestClientBuilder or upon the execution of RestClientBuilder.build(), respectively. Implementations must be declared in

META-INF/services/org.eclipse.microprofile.rest.client.spi.RestClientBuilderListener

or

META-INF/services/org.eclipse.microprofile.rest.client.spi.RestClientListener

One way of declaring a header to be included in a request is by annotating one of the resource method parameters with @HeaderValue:

@POST
@Produces(MediaType.TEXT_PLAIN)
@Consumes(MediaType.TEXT_PLAIN)
String contentLang(@HeaderParam(HttpHeaders.CONTENT_LANGUAGE) String contentLanguage, String subject);

That option is available with RESTEasy client proxies as well, but in case it is inconvenient or otherwise inappropriate to include the necessary parameter, MicroProfile Client makes a declarative alternative available through the use of the org.eclipse.microprofile.rest.client.annotation.ClientHeaderParam annotation:

@POST
@Produces(MediaType.TEXT_PLAIN)
@Consumes(MediaType.TEXT_PLAIN)
@ClientHeaderParam(name=HttpHeaders.CONTENT_LANGUAGE, value="en")
String contentLang(String subject);

In this example, the header value is hardcoded, but it is also possible to compute a value:

@POST
@Produces(MediaType.TEXT_PLAIN)
@Consumes(MediaType.TEXT_PLAIN)
@ClientHeaderParam(name=HttpHeaders.CONTENT_LANGUAGE, value="{getLanguage}")
String contentLang(String subject);

default String getLanguage() {
   return ...;
}

An instance of org.eclipse.microprofile.rest.client.ext.ClientHeadersFactory,

public interface ClientHeadersFactory {

/**
 * Updates the HTTP headers to send to the remote service. Note that providers
 * on the outbound processing chain could further update the headers.
 *
 * @param incomingHeaders - the map of headers from the inbound Jakarta RESTful Web Services request. This will
 * be an empty map if the associated client interface is not part of a Jakarta RESTful Web Services request.
 * @param clientOutgoingHeaders - the read-only map of header parameters specified on the
 * client interface.
 * @return a map of HTTP headers to merge with the clientOutgoingHeaders to be sent to
 * the remote service.
 */
MultivaluedMap<String, String> update(MultivaluedMap<String, String> incomingHeaders,
                                      MultivaluedMap<String, String> clientOutgoingHeaders);
}

if activated, can do a bulk transfer of incoming headers to an outgoing request. The default instance org.eclipse.microprofile.rest.client.ext.DefaultClientHeadersFactoryImpl will return a map consisting of those incoming headers listed in the comma separated configuration property

org.eclipse.microprofile.rest.client.propagateHeaders

In order for an instance of ClientHeadersFactory to be activated, the interface must be annotated with org.eclipse.microprofile.rest.client.annotation.RegisterClientHeaders. Optionally, the annotation may include a value field set to an implementation class; without an explicit value, the default instance will be used.

Although a ClientHeadersFactory is not officially designated as a provider, it is now (as of MicroProfile REST Client specification 1.4) subject to injection. In particular, when an instance of ClientHeadersFactory is managed by CDI, then CDI injection is mandatory. When a REST Client is executing in the context of a Jakarta RESTful Web Services implementation, then @Context injection into a ClientHeadersFactory is currently optional. RESTEasy supports CDI injection and does not currently support @Context injection.

The org.eclipse.microprofile.rest.client.ext.ResponseExceptionMapper is the client side inverse of the jakarta.ws.rs.ext.ExceptionMapper defined in Jakarta RESTful Web Services. That is, where ExceptionMapper.toResponse() turns an Exception thrown during server side processing into a Response, ResponseExceptionMapper.toThrowable() turns a Response received on the client side with an HTTP error status into an Exception. ResponseExceptionMappers can be registered in the same manner as other providers, that is, either programmatically or declaratively. In the absence of a registered ResponseExceptionMapper, a default ResponseExceptionMapper will map any response with status >= 400 to a WebApplicationException.

MicroProfile Rest Client mandates that implementations must support CDI injection of proxies. At first, the concept might seem odd in that CDI is more commonly available on the server side. However, the idea is very consistent with the microservices philosophy. If an application is composed of a number of small services, then it is to be expected that services will often act as clients to other services.

CDI (Contexts and Dependency Injection) is a fairly rich subject and beyond the scope of this Guide. For more information, see Jakarta Contexts and Dependency Injection (the specification), Jakarta EE Tutorial, or WELD - CDI Reference Implementation.

The fundamental thing to know about CDI injection is that annotating a variable with jakarta.inject.Inject will lead the CDI runtime (if it is present and enabled) to create an object of the appropriate type and assign it to the variable. For example, in

   public interface Book {
      public String getTitle();
      public void setTitle(String title);
   }

   public class BookImpl implements Book {
      
      private String title;

      @Override
      public String getTitle() {
         return title;
      }
      
      @Override
      public void setTitle(String title) {
         this.title = title;
      }
   }
   
   public class Author {
      
      @Inject private Book book; 
      
      public Book getBook() {
         return book;
      }
   }

The CDI runtime will create an instance of BookImpl and assign it to the private field book when an instance of Author is created;

In this example, the injection is done because BookImpl is assignable to book, but greater discrimination can be imposed by annotating the interface and the field with qualifier annotations. For the injection to be legal, every qualifier on the field must be present on the injected interface. For example:

   @Qualifier
   @Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
   @Retention(RetentionPolicy.RUNTIME)
   public @interface Text {}
   
   @Qualifier
   @Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
   @Retention(RetentionPolicy.RUNTIME)
   public @interface Graphic {}
   
   @Text
   public class TextBookImpl extends BookImpl { }
   
   @Graphic
   public class GraphicNovelImpl extends BookImpl { }
   
   public class Genius {
      
      @Inject @Graphic Book book;
   }

Here, the class TextBookImpl is annotated with the @Text qualifier and GraphicNovelImpl is annotated with @Graphic. It follows that an instance of GraphicNovelImpl is eligible for assignment to the field book in the Genius class, but an instance of TextBookImpl is not.

Now, in MicroProfile Rest Client, any interface that is to be managed as a CDI bean must be annotated with @RegisterRestClient:

   @Path("resource")
   @RegisterProvider(MyClientResponseFilter.class)
   public static class TestResourceImpl {

      @Inject TestDataBase db;
      
      @Path("test/{path}")
      @Consumes("text/plain")
      @Produces("text/html")
      @POST
      public String test(@PathParam("path") String path, @QueryParam("query") String query, String entity) {
         return db.getByName(query);
      }
   }

   @Path("database")
   @RegisterRestClient
   public interface TestDataBase {
      
      @Path("")
      @POST
      public String getByName(String name);
   }

Here, the MicroProfile Rest Client implementation creates a proxy for a TestDataBase service, allowing easy access by TestResourceImpl. Notice, though, that there's no indication of where the TestDataBase implementation lives. That information can be supplied by the optional @RegisterProvider parameter baseUri:

   @Path("database")
   @RegisterRestClient(baseUri="https://localhost:8080/webapp")
   public interface TestDataBase {
      
      @Path("")
      @POST
      public String getByName(String name);
   }

which indicates that an implementation of TestDatabase can be accessed at https://localhost:8080/webapp. The same information can be supplied externally with the system variable

<fqn of TestDataBase>/mp-rest/uri=<URL>

or

<fqn of TestDataBase>/mp-rest/url=<URL>

which will override the value hardcoded in @RegisterRestClient. For example,

com.bluemonkeydiamond.TestDatabase/mp-rest/url=https://localhost:8080/webapp

A number of other properties will be examined in the course of creating the proxy, including, for example

com.bluemonkeydiamond.TestDatabase/mp-rest/providers

a comma separated list of provider classes to be registered with the proxy. See the MicroProfile Client documentation for more such properties.

These properties can be simplified through the use of the configKey field in @RegisterRestClient. For example, setting the configKey as in

@Path("database")
@RegisterRestClient(configKey="bmd")
public interface TestDataBase { ... }

allows the use of properties like

bmd/mp-rest/url=https://localhost:8080/webapp

Note that, since the configKey is not tied to a particular interface name, multiple proxies can be configured with the same properties.

Proxies should be closed so that any resources they hold can be released. Every proxy created by RestClientBuilder implements the java.io.Closeable interface, so it is always possible to cast a proxy to Closeable and call close(). A nice trick to have the proxy interface explicitly extend Closeable, which not only avoids the need for a cast but also makes the proxy eligible to use in a try-with-resources block:

@Path("resource")
public interface TestResourceIntf extends Closeable {

   @Path("test")
   @GET
   public String test();
}
   
TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl("http://localhost:8081/")
                              .build(TestResourceIntf.class);
try (TestResourceIntf tr = service) {
   String s = service.test();
}

An interface method can be designated as asynchronous by having it return a java.util.concurrent.CompletionStage. For example, in

public interface TestResourceIntf extends Closeable {

   @Path("test")
   @GET
   public String test();
   
   @Path("testasync")
   @GET
   public CompletionStage<String> testAsync();
}

the test() method can be turned into the asynchronous method testAsync() by having it return a CompletionStage<String> instead of a String.

Asynchronous methods are made to be asynchronous by scheduling their execution on a thread distinct from the calling thread. The MicroProfile Client implementation will have a default means of doing that, but RestClientBuilder.executorService(ExecutorService) provides a way of substituting an application specific ExecutorService.

The classes AsyncInvocationInterceptorFactory and AsyncInvocationInterceptor in package org.eclipse.microprofile.rest.client.ext provides a means of communication between the calling thread and the asynchronous thread:

public interface AsyncInvocationInterceptorFactory {

    /**
     * Implementations of this method should return an implementation of the
     * AsyncInvocationInterceptor interface.  The MP Rest Client
     * implementation runtime will invoke this method, and then invoke the
     * prepareContext and applyContext methods of the
     * returned interceptor when performing an asynchronous method invocation.
     * Null return values will be ignored.
     *
     * @return Non-null instance of AsyncInvocationInterceptor
     */
    AsyncInvocationInterceptor newInterceptor();
}

public interface AsyncInvocationInterceptor {

    /**
     * This method will be invoked by the MP Rest Client runtime on the "main"
     * thread (i.e. the thread calling the async Rest Client interface method)
     * prior to returning control to the calling method.
     */
    void prepareContext();

    /**
     * This method will be invoked by the MP Rest Client runtime on the "async"
     * thread (i.e. the thread used to actually invoke the remote service and
     * wait for the response) prior to sending the request.
     */
    void applyContext();

    /**
     * This method will be invoked by the MP Rest Client runtime on the "async"
     * thread (i.e. the thread used to actually invoke the remote service and
     * wait for the response) after all providers on the inbound response flow
     * have been invoked.
     *
     * @since 1.2
     */
     void removeContext();
}

The following sequence of events occurs:

An AsyncInvocationInterceptorFactory class is enabled by registering it on the client interface with @RegisterProvider.

The MicroProfile Client RestClientBuilder interface includes a number of methods that support the use of SSL:

RestClientBuilder hostnameVerifier(HostnameVerifier hostnameVerifier);
RestClientBuilder keyStore(KeyStore keyStore, String keystorePassword);
RestClientBuilder sslContext(SSLContext sslContext);
RestClientBuilder trustStore(KeyStore trustStore);

For example:

KeyStore trustStore = ... ;
HostnameVerifier verifier ... ;
TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl("http://localhost:8081/")
                              .trustStore(trustStore)
                              .hostnameVerifier(verifier)
                              .build(TestResourceIntf.class);

It is also possible to configure HostnameVerifiers, KeyStores, and TrustStores using configuration properties:

The values of the ".../mp-rest/keyStore" and "../mp-rest/trustStore" parameters can be either classpath resources (e.g., "classpath:/client-keystore.jks") or files (e.g., "file:/home/user/client-keystore.jks").