How to Build a RESTful Web Service Using Jakarta EE

This guide shows you how to use Jakarta EE to make a
RESTful web service.

To create a RESTful web service using Jakarta EE, we will begin by
summarizing what we want to build.

We will build a service that will accept an HTTP GET¹
request at http://localhost:8080/restfulservice/hello.

It will respond with the following JSON payload, as the following listing
shows:

{"text": "Hello from Jakarta EE"}

We can then further customize and improve it according to our needs.

OK, now that we have specified our requirements, you will need to follow these
steps:

Set up your development environment:

• Install a Java Development Kit (JDK). Please make sure you have Java SE 8 or
  higher (we have tested with Java SE 8, Java SE 11 and Java SE 17). You can
  choose any vendor distribution of your choice from Adoptium
  as well.
• Install an application server that supports Jakarta EE. Download any of the
  Jakarta EE compatible products.
• Install Maven 3 or higher.

To install all of these, we can use the SDKMan. We can go
through the steps mentioned in the how-to guide.

How to complete this guide

In this getting started guide, you may start using Eclipse Starter for Jakarta
EE, finish each step, or skip fundamental setup stages that you already know.
You can also begin with an IDE or choose a project structure from well-known
Maven archetypes.

Create a new project with Eclipse Starter for Jakarta EE

To use Eclipse Starter for Jakarta EE, we need to take the following steps:

1. Navigate to start.jakarta.ee. This service will set up all the essential
   dependencies for an application. The current version of the Starter only
   supports Maven. In the future, we may be able to choose between Gradle and
   Maven.
   

   

2. Select the desired version of Jakarta EE from the available options. As of
   now, the options include Jakarta EE 8, Jakarta 9.1, and Jakarta 10. You may
   choose the Jakarta EE profile from Platform, Core, or Web. However, for most
   options, you may safely stick with the defaults.
3. Then specify the Group, Artifact and Version for your new project.
4. Once you have done this, the following box will let you copy a command. Copy
   the command, open your terminal, paste it, and run it.

mvn archetype:generate -DarchetypeGroupId=org.eclipse.starter -DarchetypeArtifactId=jakartaee10-minimal -DarchetypeVersion=1.1.0 -DgroupId=org.eclipse.rest -DartifactId=rest-service -Dprofile=web-api -Dversion=1.0.0-SNAPSHOT -DinteractiveMode=false

This will give us the project structure and sample code, which we can then
build and run.

Let’s explore the code structure

When we unpack the generated code, we will have the following code structure:

.
├── pom.xml
└── src
    ├── main
    │   └── java
    │       └── org
    │           └── eclipse
    │               └── restfulservice
    │                   ├── ApplicationConfig.java
    │                   └── resources
    │                       ├── Hellorecord.java
    │                       └── RestResource.java
    ├── resources
    │   └── META-INF
    │       └── beans.xml
    └── webapp

In this code structure, along with other classes and configurations, we are
interested in two classes in particular: RestResource.java and
HelloRecord.java.

Let’s open the RestResource.java file first.

package org.eclipse.restfulservice.resources;

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

@Path("hello")
public class RestResource {
    
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public HelloRecord hello(){
        return new HelloRecord("Hello from Jakarta EE");
    }
}

This defines a RESTful web service that returns a JSON representation of a
RestResource when a GET request is made to the "/hello" endpoint.

The jakarta.ws.rs.Path annotation establishes a connection between the URL
given by the user and the Java class responsible for handling the request. The
jakarta.ws.rs.GET annotation tells us we must use the HTTP GET method to
access our endpoint. The jakarta.ws.rs.Produces annotation allows you to
specify the format of the response. In our case, it will produce a
JSON² response by converting the
object of HelloRecord.

The method hello() is defined to return a HelloRecord. This is the new
record class that was released in Java 16.

package org.eclipse.restfulservice.resources;

public record HelloRecord(String text) {
}

But if you use a lower version of Java, you can change it to a traditional
POJO³ .

package org.eclipse.restfulservice.resources;

public final class HelloRecord {
  private final String text;

  public HelloRecord(String text) {
    this.text = text;
  }

  public String text() {
    return text;
  }
}

Let’s run the project from the CLI

The project structure was generated without having a runtime associated with
it. The merit of it is that we can choose from a multitude of runtimes. A list
of compatible Jakarta EE can be found here.

We will use WildFly in this tutorial.

To do that, we need to add an additional plugin to the pom.xml file.

<plugin>
  <groupId>org.wildfly.plugins</groupId>
  <artifactId>wildfly-maven-plugin</artifactId>
  <version>2.1.0.Beta1</version>
  <executions>
    <execution>
      <phase>install</phase>
      <goals>
        <goal>deploy</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Include the above plugin in the plugins sections of the pom.xml.

The wildfly-maven-plugin is used to deploy, redeploy, undeploy or run the
Jakarta EE application. There is also the ability to execute CLI commands. The
whole configuration of this plugin can be found here:
WildFly Maven Plugin – Introduction.

There are multiple ways you can configure a local instance of WildFly. Some
configurations can be found here:
WildFly Maven Plugin – Run Example.

However, in this tutorial, we can leave all the configurations as they are, as
we will use the default, and that’s enough for us.

In particular, we are interested in wildfly:run CLI command. Let’s run the
following command from the command line:

mvn clean package wildfly:run

The command above will build the app and put it on Wildfly. If Wildfly is not
installed, it will download and run it, and then the war file will be deployed.

Once the application runs, we will get the following output in the terminal:

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------in< org.eclipse:restfulservice >---------------------
[INFO] Building restfulservice 1.0.0-SNAPSHOT
[INFO] --------------------------------[ war ]---------------------------------
[INFO]
.....
skipped the log for brevity 
.....
03:35:02,323 INFO  [org.jboss.resteasy.resteasy_jaxrs.i18n] (ServerService Thread Pool -- 32) RESTEASY002225: Deploying jakarta.ws.rs.core.Application: class org.eclipse.restfulservice.ApplicationConfig
03:35:02,346 INFO  [org.wildfly.extension.undertow] (ServerService Thread Pool -- 32) WFLYUT0021: Registered web context: '/restfulservice' for server 'default-server'
03:35:02,365 INFO  [org.jboss.as.server] (management-handler-thread - 1) WFLYSRV0010: Deployed "restfulservice.war" (runtime-name : "restfulservice.war")

Let’s test the Service

Now that the service is running let’s visit http://localhost:8080/restfulservice/hello.
It should return:

{ "text": "Hello from Jakarta EE" }

Alternatively, we can curl from the command line:

curl -v http://localhost:8080/restfulservice/hello

*   Trying 127.0.0.1:8080...
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /restfulservice/hello HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.86.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Connection: keep-alive
< Content-Type: application/json
< Content-Length: 32
< Date: Sun, 18 Dec 2022 08:45:51 GMT
<
* Connection #0 to host localhost left intact
{"text":"Hello from Jakarta EE"}%      

Let us have a look at the URL structure.

http://<hostname>:<port>/<context-root>/<REST-config>/<resource-config>

Let’s unpack the URL pattern here:

Hostname: the name of the machine on which WildFly Server is installed.

Port: The WildFly Server’s listening port for incoming HTTP requests. This is
port 8080 by default, but it can be configured.

Context-root: The context root to which the deployed application has been
assigned. By default, this is the filename (without the extension) of the WAR
file that is being deployed. But it can be changed when the file is being
deployed.

REST-config: The value we have defined for the @ApplicationPath
annotation in our project. By default, it is empty, which is indicated simply
by /. We can easily configure it in our ApplicationConfig class.

Resource-config: the value defined in the @Path annotation on the Java
class defines an endpoint. In our case, "/hello" is handled by the
RestResource class.

If we want to change the REST-config part, for example, to "/api", we can
change the value in the @ApplicationPath annotation like this:

import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@ApplicationPath("/api")
public class ApplicationConfig extends Application {    
}

After making this change, if we run again, we have to change the curl command
to consume the service as follows:

curl -v http://localhost:8080/restfulservice/api/hello

Conclusion

Congratulations! You have just learned how to develop a RESTful web service
using Jakarta EE.