In this tutorial, you will create your first custom REST API using Quarkus. You will implement a new resource, return JSON responses, and make the output configurable. You will also write tests to validate your API.

Prerequisites

Before you begin, make sure that you have installed:

A JDK, version 17 or later. See the prerequisites in the Getting Started with Quarkus CLI tutorial.
The Quarkus CLI. See Step 1 in the Getting Started with Quarkus CLI tutorial.

Step 1. Create a Quarkus Project with REST and JSON support

Create a new Quarkus Project with the REST Jackson extension. Execute the following command in your project directory.

quarkus create app com.ibm.developer:module-two \
  --extension=quarkus-rest-jackson

This creates a new project called "module-two" with the Quarkus REST extension already included. Adding JSON support means that your endpoints can speak the same format that most modern applications and APIs use, making integration easy.

Step 2. Modify the example resource class

Writing your first resource is the real starting point for building Quarkus applications. REST endpoints are how your service communicates with the outside world. Once you understand this, you can extend it into real APIs. In this tutorial, you will modify an example resource class.

Open the src/main/java/org/acme/GreetingResource.java file and replace the content with the following:

package com.ibm.developer;

import java.util.Map;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/greeting")
public class GreetingResource {

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Map<String, String> greeting() {
        return Map.of("message", "Hello, Quarkus!");
    }
}

Then, start Quarkus in dev mode:

quarkus dev

Then, call the endpoint:

curl http://localhost:8080/greeting

Expected response:

{"message":"Hello, Quarkus!"}

Step 3. Add configuration support

Most applications need values that can change depending on where they run. For example, a welcome message in development might be simple, but in production it might come from an external configuration server.

Hardcoding values in code is not flexible. That is why Quarkus uses MicroProfile Config which is a standard way in the Java ecosystem to read configuration values. Instead of writing custom code to load files or environment variables, you just declare the property in your code and Quarkus provides the value. This makes your application portable and consistent across environments.

In your application, you inject the configuration properties value directly by using Context and Dependency Injection (CDI).

Open the src/main/resources/application.properties file and add this line:

greeting.message=Hello from configuration!

Update the resource class. Instead of hard coding the Greeting, we now inject the message from the configuration with the @ConfigProperty annotation (compare lines 13 and 14)

package com.ibm.developer;

import java.util.Map;

import org.eclipse.microprofile.config.inject.ConfigProperty;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/greeting")
public class GreetingResource {

    @ConfigProperty(name = "greeting.message", defaultValue = "Hello, Quarkus!")
    String message;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Map<String, String> greeting() {
        return Map.of("message", message);
    }
}

Test the endpoint again:

curl http://localhost:8080/greeting

Response should now reflect the configured value:

{"message":"Hello from configuration!"}

Step 4. Write a test for the resource

Automated tests give you confidence that your API behaves as expected. Instead of checking responses manually every time, you let the tests do the work for you. This becomes the foundation as your project grows. Quarkus integrates tightly with JUnit 5, so you can write unit and integration tests with very little setup. To test REST APIs, Quarkus uses a library called RESTAssured.

With RestAssured, it is easy to test HTTP endpoints. Instead of writing long code with HttpURLConnection or a client library, you can describe your test in a simple, readable way. Let’s change the example test in the src/test/java/org/acme/GreetingResourceTest.java file to reflect the changes in the REST endpoint and show you how easy a test definition with RESTAssured looks like.

package com.ibm.developer;

import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;

@QuarkusTest
public class GreetingResourceTest {

    @Test
    public void testGreetingEndpoint() {
        given()
                .when().get("/greeting")
                .then()
                .statusCode(200)
                .body("message", is("Hello from configuration!"));
    }
}

The @QuarkusTest annotation tells Quarkus to start your application before you run the tests. That means the /greeting endpoint is available exactly as if you were running the app in dev mode.

@Test is a JUnit 5 annotation. It marks this method as a test that should be executed. The method name is descriptive: it’s testing the greeting endpoint.

The test itself is written with RestAssured. RestAssured is a testing library that makes it easy to call HTTP endpoints and check the responses:

given() sets up the request. Here, we don’t need to add anything like headers or a body, so it’s just the default request.
.when().get("/greeting") sends an HTTP GET request to the /greeting endpoint of the running Quarkus app.
.then() switches into “assertion mode,” where you check the response.
.statusCode(200) checks that the HTTP status code is 200 OK. If the endpoint returned any other code (like 404 or 500), the test would fail.
.body("message", is("Hello from configuration!")) checks the JSON response body. It expects the JSON to contain a field message with the value Hello from configuration!.

Assuming that you still have Quarkus running, you can simply hit “r” on the console to run the tests. If not, you can start Quarkus in test mode and run the tests:

quarkus test

You should see a passing test run.

All 1 test is passing (0 skipped), 1 test was run in 168ms. Tests completed at 11:48:10.

But wait, what is “quarkus test”? We had Quarkus starting with “quarkus dev” earlier. Test means, continuous testing mode. This mode closes the feedback loop. You don’t just write code and hope it works. Instead, you see immediately if you broke something. This makes development faster and less error-prone.

When running in test mode, Quarkus automatically reruns tests whenever code or configuration changes. To see this in action:

Keep quarkus dev running.
Change the property value in application.properties.
Watch the test automatically rerun with the new output.

You can also look at the continuous testing console in your browser at http://localhost:8080/q/dev-ui/continuous-testing.

Continuous testing makes Quarkus especially productive for iterative development or Test Driven Development (TDD).

Summary

You learned how to build REST APIs in Quarkus that return JSON responses and how MicroProfile Config enables you to inject configuration values declaratively with @ConfigProperty, making your applications portable across environments. You also discovered how RESTAssured simplifies testing HTTP endpoints and how Quarkus's continuous testing mode provides immediate feedback as you code, making iterative development and test-driven development more efficient.

Building REST APIs with Quarkus

Building REST APIs with Quarkus