Build a RESTful API with Quarkus: Step-by-Step Guide
In this article, we will learn how to create a RESTful API using the Quarkus framework, which helps us to interact with our client application with the backend server.
Building an API using REST or SOAP for HTTP-based client-server communication is the first step to building our own backend for full customizability without relying on Cloud service providers. I will also share some key aspect of backend for ease of building and choosing a framework to build one and more. Let’s begin.
Note: This article isn’t generated with AI, and I haven’t done it in the past (do visit my profile), which shares real things that I’ve implemented in production apps and its techniques.
Before we learning anything new, framework or language, we first have to understand why we need to learn it and its alternatives. Now, let’s talk about it.
Introduction
What is Quarkus?
Quarkus is an open-source framework for developing cloud-native microservices. It aims to replace the old monolithic architectural framework with its Kubernetes-native approach using GraalVM and HotSpot for increased performance, lower memory usage, and startup times tailored for cloud-native deployment.
Why Quarkus?
Quarkus aims to address the challenges of modern, containerized environments, offering sub-second startup times and a significantly lower memory footprint compared to conventional Java applications.
Additionally, with its focus on building on top of proven standards like :
- Eclipse Microprofile to help developers build optimized cloud-native microservices for Java EE.
- Vert.x for its reactive paradigm used by Quarkus rest.
- RESTeasy for building RESTful API, a JAX-RS impl.
- Find the full list here.
Other popular choices
As with all technologies, each one has its own specific use cases and requirements built with a different design philosophy, but for containerized applications with cloud-native deployment, requiring minimal resource consumption and startup time. The Quarkus remains a valid choice.
- Spring Boot: As we all know, we can’t omit Spring Boot; it is known for being a mature community, ecosystem, and strong support for traditional and cloud-based applications. However, it typically has longer startup times (1–4 seconds in JVM mode) and higher memory consumption (200–500MB), which can be a drawback in containerized or serverless environments
Note: Spring Boot 3.0 introduced official, support for GraalVM Native, but it still has inherent limitations compared to frameworks like Micronaut and Quarkus, which were designed from the ground up for this purpose. Because Spring Boot’s architecture relies heavily on runtime reflection and dynamic proxies for features like dependency injection and AOP.
- Micronaut: Both Quarkus and Micronaut are designed for building cloud-native, microservices, and serverless applications, both optimized for performance with fast startup times and low memory consumption, but differ significantly in philosophy as mentioned previously, Quarkus strictly adheres to industry standards like Microprofile, Vert.x, JAX.RS (via RestEasy), which helps dev who have already experience with Java EE and its ecosystem, imposing no major learning curve. But in the case of Micronaut, which is inspired by Grails and Spring Boot, it uses an opinionated approach, instead of offering its own annotations for REST endpoints (e.g.,
@Controller,@Get). While this allows for faster startup and lower memory usage due to compile-time dependency injection and no runtime reflection, it means less reliance on external standards and a steeper learning curve for developers accustomed to Jakarta EE.
Setup / Tooling
Prerequisites:
Before we start, make sure you have the following installed on your PC:
- Java 17 or higher: Quarkus works best with Java 17 or later. Download here. (Java 17+ is required on newer Quarkus 3.7+)
- Note: If you don’t know which JDK to download, OracleJDK or OpenJDK, or even if it's from OpenJDK, and don’t know which vendor to choose, refer to my old article, which provides detailed info about this.
2. Maven: Quarkus uses Maven as a build automation tool. It also supports Gradle as a build tool. You can install Maven from here.
3. A text editor or IDE: IntelliJ IDEA, Eclipse, Netbeans, or VS Code are great options.
Note: Quarkus supports Kotlin well and good through its extension, but the IDE that supports Kotlin like Eclipse, Netbeans, and VS Codeofficially through a plugin is stale and limited as of now. But the Kotlin Language server is in development, which helps to use Kotlin better in VS Code and beyond. But in this article, we’re going to use Java + VSCode. RedHat provides excellent support for Quarkus through its Quarkus tolling extension, which supports: Snippet support, Wizards for creating new projects in the editor, and much more.
3. GraalVM (optional): For native image compilation, download GraalVM from here.
Step 1: Installing Quarkus
Installing Quarkus CLI
The Quarkus CLI is available via sdkman, Homebrew, or as a direct download.
For macOS/Linux:
sdk install quarkusFor Windows, use the scooppackage manager or via other methods:
scoop install quarkus-cliVerify the installation by running this command in the CMD
quarkus --versionStep 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.28.2:create \
-DprojectGroupId=com.mubarak.hello-quarkus \
-DprojectArtifactId=quarkus-hello-world \
-DclassName="com.mubarak.GreetingResource" \
-Dpath="/hello" \What does the following command do:
DprojectGroupId=: The group ID for your project.DprojectArtifactId=: The artifact ID or the name of your project.DclassName="": The name of the class to handle your REST endpoint.Dpath="/hello": The path for your REST API endpoint.
Or we can also create a Quarkus project using the web GUI wizard at this URL: https://code.quarkus.io. Choose your extensions and click generate your app that downloads the ZIP, extract it, and import it into your favourite IDE/Editor. In my case, that is VSCode
Step 3: Explore the created project
Once the project is generated, you’ll have the following structure:
quarkus-hello-world
│
├── src
│ └── main
│ ├── kotlin
│ │ └── com
│ │ └── mubarak
| | └── hello
| | └── quarkus
│ │ └── GreetingResource.java
│ └── resources
│ └── application.properties
└── pom.xmlKey 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 build configuration file, which includes all project dependencies.
Step 4: Running Your Quarkus Application
Quarkus builds with developer joy into its core design model, so it provides many useful tools in development, like Dev UI, Live Coding, Remote Development, and more
To start the application in development mode, run the following CMD:
./mvnw quarkus:dev Visit http://localhost:8080/hello endpoint in your browser to see the response from the Quarkus and verify the logic that we have written in GreetingResource.kt
package com.mubarak.quarkus;
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 from Quarkus REST";
}
}Output in the browser:
Hello Quarkus from RESTStep 5: Building our Own REST Endpoint
Now let’s build our own RESTful endpoint with a passing value via path and using the @GET HTTP method. There are a lot of HTTP methods like
Learn more about HTTP methods here.
package com.mubarak.quarkus;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
@Path("/hello")
public class QueryResource {
@GET
@Path("{field}/{exp:\\d+}")
public String personalisedQuery(@PathParam("field") String field,
@PathParam("exp") int exp) {
return "Are you really have " + exp + " years of experience in your " + field + " field?";
}
@GET
public String genericHello() {
return "Hello interactor";
}
}
-> http://localhost:8080/api/hello/Civil/7
Now, when we make an request to the above URL while passing values for the path params like field and exp, the output is:
Are you really have 7 years of experience in your Civil field?Step 6: Packaging the Application
Now let’s package this application into a JAR, That's the usual thing we do in production using manually or using CD like GitHub Actions. Run the following Maven command:
mvn packageThis will generate a JAR file inside the target/ directory.
You can run it with:
java -jar target/quarkus-app/quarkus-run.jarVisit http://localhost:8080/hello, and your application should work as expected as before.
Step 7: Building a Native Image (Optional)
Quarkus has GraalVM native image support in its core, which results in a smaller, optimized, and faster executable. To build a native image, you need GraalVM installed.
Follow this guide to set up GraalVM on Quarkus. https://quarkus.io/guides/building-native-image
Run the following Maven command:
mvn package -PnativeOnce complete, you’ll get a native executable in the target/ directory.
Run it with:
./target/mubarak.hello.quarkus-1.0.0-SNAPSHOT-runnerThis will start the application almost instantly with much lower memory consumption compared to the JVM mode.
Conclusion
Greetings! You’ve just built your very first Quarkus microservice. Now, you’ve seen the power of Quarkus in action. With its development features like DEV UI, Live loading, and more, it offers fast startup times and a smooth developer experience for building cloud-native microservices.
There are a lot of things I’ve planned to create an article about in future, like deploying a full custom backend on our own VPS. I hope this article might be a good introduction to Quarkus and its functionality. If you like it, share it with your friends. And I’d like to apologize for not publishing a new article/blog in the past 3 months because of extensive work on MBCompass and learning a new tech stack. But in the upcoming months in the future, I will continue my consistency as before. I’m telling this at the end of the story, not to waste your time.
Thank you! Always professional and best effort content!
