Quarkus REST API

Building a Mock Device Server with Quarkus

 

Introduction

 

What are we going to build?
In this tutorial, we will create a mock device server using Quarkus. This server will expose a REST API that generates and returns mock device data based on a request parameter.

What will our API do?
GET /devices?amount=5 → Returns 5 randomly generated devices.

What are we going to use?
✅ Java 17
✅ Quarkus – A lightweight Java framework for modern applications.
✅ Jackson – For JSON serialization.
✅ Maven – For managing dependencies.

 

Step 1: Setting up the Quarkus Project

Creating the Maven Project
If you haven’t already created a Quarkus project, you can generate it with the following command:

mvn io.quarkus.platform:quarkus-maven-plugin:3.18.3:create \
-DprojectGroupId=tech.devblueprint \
-DprojectArtifactId=quarkus-device-mock-server \
-Dextensions="resteasy-jackson"

 

Step 2: Configuring Dependencies

In pom.xml, add the necessary dependencies:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>tech.devblueprint</groupId>
    <artifactId>quarkus-device-mock-server</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <quarkus.version>3.18.3</quarkus.version>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>io.quarkus.platform</groupId>
                <artifactId>quarkus-bom</artifactId>
                <version>${quarkus.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-resteasy</artifactId>
        </dependency>
        <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-resteasy-jackson</artifactId>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>io.quarkus</groupId>
                <artifactId>quarkus-maven-plugin</artifactId>
                <version>${quarkus.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>build</goal>
                            <goal>generate-code</goal>
                            <goal>generate-code-tests</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>


</project>

Explanation: ✅ quarkus-resteasy – Enables REST API functionality.

 

✅ quarkus-resteasy-jackson – Provides automatic JSON serialization using Jackson.

Defining the Data Model The DeviceDTO class represents a mock device with randomly generated properties.


package tech.devblueprint.dto;

import java.util.UUID;

public class DeviceDTO {
    private UUID id;
    private String deviceOs;
    private String serial;

    public DeviceDTO(UUID id, String deviceOs, String serial) {
        this.id = id;
        this.deviceOs = deviceOs;
        this.serial = serial;
    }

    public UUID getId() {
        return id;
    }

    public String getDeviceOs() {
        return deviceOs;
    }

    public String getSerial() {
        return serial;
    }
}

Implementing the Business Logic The DeviceService class is responsible for generating mock devices based on the requested amount.

package tech.devblueprint.service;

import jakarta.enterprise.context.ApplicationScoped;
import tech.devblueprint.dto.DeviceDTO;

import java.util.List;
import java.util.UUID;
import java.util.stream.IntStream;

@ApplicationScoped
public class DeviceService {

    private static final List<String> OS_TYPES = List.of("Android", "iOS", "Linux");

    public List<DeviceDTO> generateDevices(int amount) {
        return IntStream.range(0, amount)
                .mapToObj(i -> new DeviceDTO(
                        UUID.randomUUID(),
                        OS_TYPES.get((int) (Math.random() * OS_TYPES.size())),
                        "SN-" + UUID.randomUUID().toString().substring(0, 8)
                ))
                .toList();
    }
}

@ApplicationScoped is a Jakarta CDI annotation that marks a class as a bean with a single instance for the entire application, managed by the CDI container.

Exposing the REST API

 

Finally, we create a REST endpoint in DeviceResource.java to serve mock device data.

 

package tech.devblueprint.controller;

import jakarta.inject.Inject;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import tech.devblueprint.dto.DeviceDTO;
import tech.devblueprint.service.DeviceService;

import java.util.List;

@Path("/devices")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class DeviceResource {

    @Inject
    DeviceService deviceService;

    @GET
    public List<DeviceDTO> getDevices(@QueryParam("amount") @DefaultValue("5") int amount) {
        return deviceService.generateDevices(amount);
    }
}

@Inject is a Jakarta CDI (Contexts and Dependency Injection) annotation that indicates a dependency should be automatically injected by the Quarkus CDI container, as Quarkus relies on Jakarta CDI to manage all bean components (@ApplicationScoped, @RequestScoped), and it is part of the Jakarta Dependency Injection (jakarta.inject) specification rather than a Quarkus-specific annotation.

Step 3: Running and Testing the Server

 

Starting the Server

 

Run the following command to start Quarkus in Dev Mode:

mvn quarkus:dev

Run the following command to start Quarkus in Dev Mode:

mvn quarkus:dev

Now, test the API:

curl "http://localhost:8080/devices?amount=5"
[
  {
    "id": "fd13f57a-6464-4693-9cc8-df848c74c881",
    "deviceOs": "Android",
    "serial": "SN-bcba105a"
  },
  {
    "id": "1a3d827d-998a-4915-810a-58838082a874",
    "deviceOs": "Android",
    "serial": "SN-df5556ee"
  },
  {
    "id": "fe3fab4e-6ff1-41f7-872e-6c1b51f797d5",
    "deviceOs": "Android",
    "serial": "SN-2ddcb750"
  },
  {
    "id": "bfeea0e3-de6a-4ab5-8869-42c6880cfbfe",
    "deviceOs": "iOS",
    "serial": "SN-55636dc7"
  },
  {
    "id": "72892a6f-802a-4f7e-9e32-54c41ce88290",
    "deviceOs": "Android",
    "serial": "SN-efbcda0c"
  }
]

Conclusion

🎉 Congratulations! You have successfully built a mock server using Quarkus. Now you have a solid foundation to mock APIs for testing and development!