A simple example of MicroProfile REST Client API

MicroProfile REST Client API provides a type-safe approach to invoke RESTful services over HTTP. It relies on JAX-RS APIs for consistency and easier reuse, therefore you won’t need a specific extension to be added in WildFly to use this API. Let’s see a sample application which is composed of a Server Endpoint and a REST Client Endpoint which acts as an interface for the Server Endpoint.

Requirements:

In order to run this tutorial you will need:

• WildFly application server version 19 or newer
• Maven
• JDK (at least 1.8)

Creating the REST Server Endpoint

The Server Endpoint exposes our SimpleRESTService:

@Path("/")
public class SimpleRESTService {
	@GET
	@Path("/text")
	public String getHello () 
	{
		return "hello world!";
	} 
	@GET
	@Path("/json")
	@Produces(MediaType.APPLICATION_JSON)
	public SimpleProperty getPropertyJSON () 
	{
        SimpleProperty p = new SimpleProperty("key","value");
		return p;
	}
	@GET
	@Path("/xml")
	@Produces(MediaType.APPLICATION_XML)
	public SimpleProperty getPropertyXML () 
	{
        SimpleProperty p = new SimpleProperty("key","value");
		return p;
	}
}

This Endpoint is activated by the following JAX-RS activator:

@ApplicationPath("/api")
public class JaxRsActivator extends Application {
    
}

You can deploy the Endpoint as usual with as follows:

$ mvn clean package wildfly:deploy

Check that the application has been deployed successfully:

15:12:46,302 INFO  [org.jboss.as.server.deployment] (MSC service thread 1-1) WFLYSRV0027: Starting deployment of "ee-microprofile-rest-server.war" (runtime-name: "ee-microprofile-rest-server.war")
15:12:46,374 INFO  [org.jboss.resteasy.resteasy_jaxrs.i18n] (ServerService Thread Pool -- 116) RESTEASY002225: Deploying javax.ws.rs.core.Application: class com.itbuzzpress.jaxrs.activator.JaxRsActivator
15:12:46,378 INFO  [org.wildfly.extension.undertow] (ServerService Thread Pool -- 116) WFLYUT0021: Registered web context: '/ee-microprofile-rest-server' for server 'default-server'

Now let’s move to the REST Client application.

Creating the REST Client Endpoint

In order to create a MicroProfile REST Client we need to add an interface which uses the proper JAX-RS and MicroProfile annotations:

@RegisterRestClient(baseUri = "http://localhost:8080/ee-microprofile-rest-server/rest")
@Path("/api")
public interface SimpleRESTServiceItf {
	@GET
	@Path("/text")
	public String getHello();

	@GET
	@Path("/json")
	@Produces(MediaType.APPLICATION_JSON)
	public SimpleProperty getPropertyJSON();

	@GET
	@Path("/xml")
	@Produces(MediaType.APPLICATION_XML)
	public SimpleProperty getPropertyXML();

}

This interface registers a remote REST Endpoint using the @RegisterRestClient annotation that will connect to the Server Endpoint. For this purpose, we have provided the same set of API which are available in the remote Endpoint as interface methods.

Next, we need an actual JAX-RS Resource that will be available on the Client application as proxy to the Remote Endpoint:

@Path("/proxy")
@ApplicationScoped
public class SimpleRESTEndpoint {

    @Inject
    @RestClient
    SimpleRESTServiceItf service;

    @GET
    @Path("/text")
    public String getHello() {
        return service.getHello();
    }

    @GET
    @Path("/json")
    @Produces(MediaType.APPLICATION_JSON)
    public SimpleProperty getPropertyJSON(){
        return service.getPropertyJSON();
    }

    @GET
    @Path("/xml")
    @Produces(MediaType.APPLICATION_XML)
    public SimpleProperty getPropertyXML() {
        return service.getPropertyXML();
    }

}

By injecting the SimpleRESTServiceItf as @RestClient, we will be able to proxy the remote REST Endpoint.

Now we are ready to build, deploy and test our application.

Build and deploy the application:

$ mvn clean package wildfly:deploy

Let’s check first the Server Endpoint’s text method:

$ curl http://localhost:8080/ee-microprofile-rest-server/api/text
hello world!

Now, try to reach the same method using the Client REST API_

$ curl http://localhost:8080/ee-microprofile-rest-client/proxy/text
hello world!

Configuring the REST client base URL/URI dynamically

To configure the base URI of the REST client dynamically the MicroProfile REST Client can the MicroProfile Config specification.

The name of the property for the base URI of our REST client needs to follow a certain convention. Create a new file `src/main/resources/META-INF/microprofile-config.properties` with the following content:

com.itbuzzpress.jaxrs.service.SimpleRESTServiceItf/mp-rest/url=http://localhost:8080/ee-microprofile-rest-server
com.itbuzzpress.jaxrs.service.SimpleRESTServiceItf/mp-rest/scope=javax.inject.Singleton

This configuration means that:

• All requests performed using com.itbuzzpress.jaxrs.service.SimpleRESTServiceItf will use http://localhost:8080/ee-microprofile-rest-server as a base URL.
• The default scope of com.itbuzzpress.jaxrs.service.SimpleRESTServiceItf will be @Singleton. Supported scope values are @Singleton, @Dependent, @ApplicationScoped and @RequestScoped. The default scope is @Dependent.

This tutorial is an excerpt from the book “Practical Enterprise Development” available on ItBuzzPress:

Source code available here: https://bit.ly/3busStm