How to Consume REST API in Quarkus

1. Introduction

Microservices architecture has transformed how we design and build applications by breaking down monolithic systems into smaller, loosely coupled services. These services communicate with each other primarily through REST APIs, making it essential to understand how to consume these APIs effectively.

Quarkus is a modern Java framework optimized for microservices.

In this tutorial, we’ll explore how to create a dummy REST API in Quarkus and demonstrate various methods to consume it using different clients. This knowledge is crucial for building robust and efficient microservice-based applications.

2. Creating the API

To get started, we need to set up a basic Quarkus application and create a dummy REST API that returns a list of posts.

2.1. Creating Post Entity

We’re going to create a Post entity that our API will return:

public class Post {
    public Long id;
    public String title;
    public String description;

    // getters, setters, constructors
}

2.2. Creating Post Resource

Also, for this example, we’ll create a resource that will return a list of posts in JSON format:

@Path("/posts")
public class PostResource {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<Post> getPosts() {
        return Arrays.asList(
          new Post(1L, "Post One", "This is the first post"),
          new Post(2L, "Post Two", "This is the second post")
        );
    }
}

We’ll consume this API in our new application.

2.3. Testing the API

We can test our new API using curl:

curl -X GET http://localhost:8080/posts

By calling this, we’ll get a JSON list of posts:

[
  {
    "id": 1,
    "title": "Post One",
    "description": "This is the first post"
  },
  {
    "id": 2,
    "title": "Post Two",
    "description": "This is the second post"
  }
]

Now, having this API functional, we’ll see how to consume it inside another Quarkus application instead of curl.

3. Consuming API with Rest Client

Quarkus supports MicroProfile Rest Client, a powerful and type-safe HTTP client, which simplifies consuming RESTful APIs by providing an interface-driven approach.

3.1. Maven Dependency

To get started, we need to include the Rest Client dependency in our pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-client</artifactId>
    <version>3.13.3</version>
</dependency>

This will provide the necessary components to work with the MicroProfile Rest Client.

3.2. Defining the Client Interface

We’ll define an interface representing the remote API we want to consume. This interface should mirror the structure of the API’s endpoints:

@Path("/posts")
@RegisterRestClient(configKey = "post-api")
public interface PostRestClient {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    List<Post> getAllPosts();
}

The @RegisterRestClient annotation registers this interface as a REST client, and the configKey attribute is used to bind configuration properties. The @Path annotation specifies the base path of the API.

3.3. Configuration

The base URL for the REST client can be specified in the application.properties file using the configKey defined in the interface:

quarkus.rest-client.post-api.url=http://localhost:8080

By doing that, we can easily modify the API’s base URL without changing the source code. Besides that, we can also change the default port of the application:

quarkus.http.port=9000

We do this because the first API runs on the default port 8080.

3.4. Using the Rest Client

Once the Rest Client interface is defined and configured, we can inject it into a Quarkus service or resource class using the @RestClient annotation. This annotation tells Quarkus to provide an instance of the specified interface configured with the base URL and other settings:

@Path("rest-client/consume-posts")
public class PostClientResource {
    @Inject
    @RestClient
    PostRestClient postRestClient;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<Post> getPosts() {
        return postRestClient.getAllPosts();
    }
}

3.5. Testing the Application

Now, with everything set up, we can test our application. We can do that by running a curl command:

curl -X GET localhost:9000/rest-client/consume-posts

This should return our JSON list of posts.

4. Consuming API with JAX-RS Client API

The JAX-RS Client API is a part of the Java API for RESTful Web Services (JAX-RS) specification. It provides a standard, programmatic way to create HTTP requests and consume RESTful web services.

4.1. Maven Dependency

To start, we need to include RESTEasy Client dependency in our pom.xml:

<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-client</artifactId>
    <version>6.2.10.Final</version>
</dependency>

This dependency brings in RESTEasy, the JAX-RS implementation used by Quarkus, and the client API necessary for making HTTP requests.

4.2. Implementing the JAX-RS Client

To consume a REST API, we’ll create a service class that sets up a JAX-RS client, configures the target URL, and processes the responses:

@ApplicationScoped
public class JaxRsPostService  {
    private final Client client;
    private final WebTarget target;

    public JaxRsPostService() {
        this.client = ClientBuilder.newClient();
        this.target = client.target("http://localhost:8080/posts");
    }

    public List<Post> getPosts() {
        return target
          .request()
          .get(new GenericType<List<Post>>() {});
    }
}

We initialize the client using the builder pattern and configure the target with the base URL for API requests.

4.3. Exposing the API Through a Resource Class

Now, all we need to do is to inject our service into our resources:

@Path("jax-rs/consume-posts")
public class PostClientResource {
    @Inject
    JaxRsPostService jaxRsPostService;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<Post> getJaxRsPosts() {
        return jaxRsPostService.getPosts();
    }
}

4.4. Testing the Application

Now we can test again our API using curl:

curl -X GET localhost:9000/jax-rs/consume-posts

5. Consuming API with Java 11 HttpClient

Java 11 introduced a new HTTP client API that provides a modern, asynchronous, and feature-rich way to handle HTTP communications. The java.net.http.HttpClient class allows us to send HTTP requests and process responses easily, and in this section, we’ll learn how to do it.

5.1. Creating the HttpClient Service

No additional dependencies are required in this example, Java 11’s HttpClient being part of the standard library.

Now, we’ll create a service class that manages the HttpClient:

@ApplicationScoped
public class JavaHttpClientPostService {
    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;

    public JavaHttpClientPostService() {
        this.httpClient = HttpClient.newHttpClient();
        this.objectMapper = new ObjectMapper();
    }

    public List<Post> getPosts() {
        HttpRequest request = HttpRequest.newBuilder()
          .uri(URI.create("http://localhost:8080/posts"))
          .GET()
          .build();

        try {
            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
            return objectMapper.readValue(response.body(), new TypeReference<ArrayList<Post>>() { });
        }
        catch (IOException | InterruptedException e) {
            throw new RuntimeException("Failed to fetch posts", e);
        }
    }

}

In this class, we initialize the HttpClient instance and an ObjectMapper instance from Jackson that we’ll use to parse JSON responses into Java objects.

We create an HttpRequest object, specifying the URI of the API endpoint and the HTTP method. After that, we send the request using the send() method of the HttpClient instance. We handle the response using BodyHandlers.ofString(), which converts the body into a string. We’ll convert that string into our Post object using the ObjectMapper.

5.2. Creating the Resource

To make the fetched data available via our application, we’ll expose the JavaHttpClientPostService through a resource class:

@Path("/java-http-client/consume-posts")
public class JavaHttpClientPostResource {
    @Inject
    JavaHttpClientPostService postService;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<Post> getPosts() {
        return postService.getPosts();
    }
}

5.3. Testing the Application

Now we can test the app again using curl:

curl -X GET localhost:9000/java-http-client/consume-posts

6. Conclusion

In this article, we demonstrated how to consume REST APIs in Quarkus using the Quarkus RestClient, JAX-RS Client API, and Java 11 HttpClient.

Each method has advantages: the RestClient integrates seamlessly with Quarkus, the JAX-RS Client API offers flexibility, and Java 11’s HttpClient brings modern features from the JDK. Mastering these techniques enables effective communication between microservices, making building scalable and efficient architectures in Quarkus easier.