A Beginner’s Guide to Quarkus: Build Your First Java Microservice/API

Image taken from Google

The rise of cloud-native applications has pushed developers toward more efficient frameworks, and Quarkus is one that stands out for Java developers. Designed for Kubernetes and optimized for GraalVM, Quarkus promises low memory consumption, fast startup times, and an overall developer-friendly experience. If you’re looking to dive into microservices with Java, Quarkus is a great place to start.

In this article, we’ll walk through the steps to set up Quarkus on your machine and build your first Java microservice. By the end, you’ll have a simple REST API running locally.

Quarkus logo taken from official site

What You’ll Learn

• Setting up Quarkus
• Creating a new Quarkus project
• Building and running your microservice
• Adding a simple REST endpoint

Prerequisites

Before we start, make sure you have the following installed on your machine:

1. Java 11 or higher: Quarkus works best with Java 11 or later. Download here.
2. Apache Maven: Quarkus uses Maven for dependency management and project building. You can install Maven from here.
3. A text editor or IDE: IntelliJ IDEA, Eclipse, or VS Code are great options.
4. GraalVM (optional but recommended): For native image compilation, download GraalVM from here.

Application startup process, imgae taken from infoQ

Step 1: Installing Quarkus

You don’t need to manually install Quarkus; it’s automatically set up when you initialize a new Quarkus project using the Maven Quarkus plugin.

However, it’s good practice to install the Quarkus CLI tool for easier project management.

Installing Quarkus CLI

The Quarkus CLI is available via sdkman, Homebrew, or as a direct download.

For macOS/Linux:

sdk install quarkus

For Windows, use the manual method or choco package manager:

choco install quarkus

Once installed, verify it by running:

quarkus --version

This will confirm that the CLI is ready for use.

Step 2: Creating Your First Quarkus Project

Let’s create a Quarkus project using Maven. Open your terminal and run the following command:

mvn io.quarkus:quarkus-maven-plugin:3.0.0.Final:create \
    -DprojectGroupId=com.example \
    -DprojectArtifactId=quarkus-hello-world \
    -DclassName="com.example.GreetingResource" \
    -Dpath="/hello"

Breakdown of the command:

• DprojectGroupId=com.example: The group ID for your project.
• DprojectArtifactId=quarkus-hello-world: The artifact ID or the name of your project.
• DclassName="com.example.GreetingResource": The name of the class to handle your REST endpoint.
• Dpath="/hello": The path for your REST API endpoint.

This will generate a new project with a basic REST API that listens on /hello.

Step 3: Exploring the Project Structure

Once the project is generated, you’ll have the following structure:

quarkus-hello-world
│
├── src
│   └── main
│       ├── java
│       │   └── com
│       │       └── example
│       │           └── GreetingResource.java
│       └── resources
│           └── application.properties
└── pom.xml

Key files:

• GreetingResource.java: This is where the REST endpoint is defined.
• application.properties: This file holds the configuration for your Quarkus application.
• pom.xml: Maven configuration file, which includes all project dependencies.

Step 4: Running Your Quarkus Application

To run the Quarkus application, navigate to your project directory:

cd quarkus-hello-world

Now, start the application in development mode with:

mvn quarkus:dev

This will start a Quarkus instance with live reload enabled. Any changes you make to the code will immediately reflect without needing to restart the server.

Once it’s up, visit http://localhost:8080/hello in your browser or use curl:

curl http://localhost:8080/hello

You should see the output:

Hello, RESTEasy

Step 5: Customizing the REST Endpoint

The default REST API returns a simple “Hello, RESTEasy” message, but let’s modify it to return a personalized greeting.

Open GreetingResource.java located at src/main/java/com/example/GreetingResource.java. Modify it to the following:

package com.example;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
@Path("/hello")
public class GreetingResource {
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello, Quarkus!";
    }
}

Save the file and check the browser again by reloading http://localhost:8080/hello. The response should now be:

Hello, Quarkus!

Adding Parameters

Let’s make the API a little more dynamic by accepting a parameter.

Update GreetingResource.java:

package com.example;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MediaType;
@Path("/hello")
public class GreetingResource {
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@QueryParam("name") String name) {
        return "Hello, " + name + "!";
    }
}

Now, visit http://localhost:8080/hello?name=John. You should see:

Hello, John!

Step 6: Packaging the Application

To run your Quarkus application outside of dev mode, you’ll need to package it. Run the following Maven command:

mvn package

This will generate a runnable JAR file inside the target/ directory.

You can run it with:

java -jar target/quarkus-hello-world-1.0.0-SNAPSHOT-runner.jar

Visit http://localhost:8080/hello, and your application should work as expected.

Step 7: Building a Native Image (Optional)

Quarkus excels in native image generation using GraalVM, resulting in a smaller, faster executable. To build a native image, you need GraalVM installed.

Run the following Maven command:

mvn package -Pnative

Once complete, you’ll get a native executable in the target/ directory.

Run it with:

./target/quarkus-hello-world-1.0.0-SNAPSHOT-runner

This will start the application almost instantly with much lower memory consumption compared to the JVM mode.

Step 8: Deploying to Kubernetes (Optional)

Since Quarkus is Kubernetes-native, you can easily deploy your application to Kubernetes or OpenShift. You can add Kubernetes configurations to your project by adding the following to your pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-kubernetes</artifactId>
</dependency>

Then, use the following command to generate Kubernetes deployment manifests:

mvn clean package -Dquarkus.kubernetes.deploy=true

This will create YAML files that can be used to deploy the app into your Kubernetes cluster.

Conclusion

Congratulations! You’ve built your first Quarkus-based Java microservice. From setting up a simple REST endpoint to running the application in native mode, you’ve seen the power of Quarkus in action. It offers a rich ecosystem, blazing fast startup times, and a smooth developer experience for building cloud-native microservices.

Quarkus is not just limited to simple services — you can explore its integrations with databases, messaging systems, and cloud providers to build robust applications.

Happy coding!

Let me know if you have any questions, and I’d love to hear your experiences with Quarkus in the comments!