Build a REST API with Java, Jakarta EE and Helidon

Introduction

In this tutorial, you will learn how to set up an REST service using Jakarta EE. You will create a simple web service with two endpoints. The first one will return a JSON array of Strings and the second one will return a JSON object.

Maven setup

To build our Helidon REST service with Maven, we need to edit the POM file. This file defines essential project information like its name, group ID, and version. More importantly, it specifies the Helidon framework as a parent project, inheriting its core functionalities. Additionally, the POM declares dependencies needed for our service to function, such as the helidon-microprofile bundle, and configures plugins for building and packaging the application.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

<?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>com.davidvlijmincx</groupId>
    <artifactId>RestEndpointWithJava</artifactId>
    <version>1.0-SNAPSHOT</version>

    <parent>
        <groupId>io.helidon.applications</groupId>
        <artifactId>helidon-mp</artifactId>
        <version>4.0.11</version>
        <relativePath/>
    </parent>


<!--    If you want to use the Main provided by Helidon-->
    <properties>
        <mainClass>io.helidon.microprofile.cdi.Main</mainClass>
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.helidon.microprofile.bundles</groupId>
            <artifactId>helidon-microprofile</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <executions>
                    <execution>
                        <id>copy-libs</id>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

This POM file sets up your Helidon project. It defines basic project details, includes necessary dependencies, and configures Maven for building your REST service. Let's now configure the beans for the project.

Discover beans

This XML file defines the “beans” used in our application. Think of beans like little building blocks.
Each bean represents a specific object in your program that can perform tasks or hold data. This file tells the application which beans exist and how to find them. For the application we are building the class holding the REST endpoints is a bean for example.

The XML file needs to be placed in a specific location. Inside your project at the same level as the java directory create the following directories if you don't have them already /resources/META-INF. Inside the META-INF directory, you need to create a file called beans.xml with the the following content:

1
2
3
4
5
6

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="https://jakarta.ee/xml/ns/jakartaee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/beans_3_0.xsd"
       bean-discovery-mode="annotated">
</beans>

This tells Helidon how it should find beans. In this case, it will look for annotated classes. Next, we'll dive into creating the REST endpoints.

Creating REST endpoints

REST endpoints are how we interact with this application. The purpose of an endpoint is to receive a request, process it, and return a response. In the following example, two endpoints are defined one will return a list of Frameworks, and the second returns an object instance.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import java.util.List;

@Path("frameworks")
public class FrameworkEndPoint {
    
    @GET
    public List<String> getFrameworks() {
        return List.of("Helidon","Quakrus", "micronaut");
    }


    @GET
    @Path("someData")
    public SomeData someData() {
        return new SomeData("Helidon","It is a great framework to work with",5);
    }
}

These endpoints will by default return a JSON response, which means that your return object will be marshaled into a JSON object.

When calling the first endpoint using http://localhost:7001/frameworks/ will return:

1
2
3
4
5

[
    "Helidon",
    "Quakrus",
    "micronaut"
]

The Second endpoint using this URL http://localhost:7001/frameworks/someData will turn the object instance into the following JSON:

1
2
3
4
5

{
    "description": "It is a great framework to work with",
    "name": "Helidon",
    "number": 5
}

With everything set up, it is time to see how to start your web service.

Starting the web server with a Main class

If you like to use your own main class you only need to create and start a server. You can start the server like this:

1
2
3
4
5
6
7
8

import io.helidon.microprofile.server.Server;

public class Main {
    
    public static void main(String[] args) {
        Server.create().start();
    }
}

This will create and start a server. When you start this method you can try and access the endpoints you just created.

Using the build in Main class

You don't have to create your own Main class and method. You can also use the one that is part of Helidon. To use this class you have to change the run configuration in your IDE to use io.helidon.microprofile.cdi.Main. If you use Maven you already configured this by adding the following to the pom.xml:

1
2
3

<properties>
    <mainClass>io.helidon.microprofile.cdi.Main</mainClass>
</properties>

With the main class configured, you can open a shell and navigate to the project directory, and run the following command:

1

mvn clean package

Clean will up the target directory if it already was created and package the code into a jar file.

With the jar file created, you can run it using the following command:

1

java -jar target/RestEndpointWithJava.jar 

This will start the application after which you can access the REST endpoints you created earlier.

Conclusion

This post showed how to implement a REST service straightforwardly using Jakarta. This post is the first in a series of creating production-like application in small steps.

You can find the complete project here https://github.com/davidtos/RestEndpointWithJavaAndHelidon