Tutorial: Your first RESTful web service

Create a new Jakarta EE project with JAX-RS

IntelliJ IDEA includes a dedicated wizard for creating Jakarta EE projects based on various Jakarta EE implementations. In this tutorial, we will create a simple web application.

1. Open the New Project wizard:

   • If you are on the Home screen, select New | Project….

   • If you have another project open, go to File | New | Project.

2. From the Generators list on the left, select Jakarta EE.

   

3. Set up the project settings as follows:

   • Name: JakartaRESTHelloWorld

   • Location: leave as-is

   • Create Git repository: leave as-is

   • Template: REST service

   • Application server: <No application server>

   • Language: Java

   • Build system: Maven

   • Group: leave as-is

   • Artifact: leave as-is

   • JDK: Eclipse Temurin 21

   When you are ready, click Next.

4. From the Version drop-down list, select Jakarta EE 11 because that's what Tomcat 11 used in this tutorial is compatible with. Jakarta EE 9.1 because that's what GlassFish 6.2.5 used in this tutorial is compatible with.

   Because we chose the REST service template in the previous step, some specifications are already selected in the Dependencies list. For the purposes of this tutorial, you do not need to select any other dependencies.

   

5. Because we chose the REST service template in the previous step, some specifications are already selected in the Dependencies list. However, we also need to select their implementations: Eclipse Jersey Server and Weld SE.

   

6. Click Create.

Explore the default project structure

IntelliJ IDEA creates a project with some boilerplate code that you can build and deploy successfully.

• pom.xml is the Project Object Model with Maven configuration information, including dependencies and plugins necessary for building the project.

  <?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 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>org.example</groupId> <artifactId>RestTomcatHelloWorld</artifactId> <version>1.0-SNAPSHOT</version> <name>RestTomcatHelloWorld</name> <packaging>war</packaging> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.target>21</maven.compiler.target> <maven.compiler.source>21</maven.compiler.source> <junit.version>5.11.0-M2</junit.version> </properties> <dependencies> <dependency> <groupId>jakarta.servlet</groupId> <artifactId>jakarta.servlet-api</artifactId> <version>6.1.0</version> <scope>provided</scope> </dependency><dependency> <groupId>org.glassfish.jersey.containers</groupId> <artifactId>jersey-container-servlet</artifactId> <version>4.0.0-M1</version> </dependency> <dependency> <groupId>org.glassfish.jersey.media</groupId> <artifactId>jersey-media-json-jackson</artifactId> <version>4.0.0-M1</version> </dependency> <dependency> <groupId>org.glassfish.jersey.inject</groupId> <artifactId>jersey-cdi2-se</artifactId> <version>4.0.0-M1</version> </dependency><dependency> <groupId>org.jboss.weld.se</groupId> <artifactId>weld-se-core</artifactId> <version>6.0.0.Beta1</version> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-api</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-engine</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.4.0</version> </plugin> </plugins> </build> </project>
  <?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 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>RestTomcatHelloWorld</artifactId> <version>1.0-SNAPSHOT</version> <name>RestTomcatHelloWorld</name> <packaging>war</packaging> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.target>11</maven.compiler.target> <maven.compiler.source>11</maven.compiler.source> <junit.version>5.9.2</junit.version> </properties> <dependencies> <dependency> <groupId>jakarta.servlet</groupId> <artifactId>jakarta.servlet-api</artifactId> <version>5.0.0</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.glassfish.jersey.containers</groupId> <artifactId>jersey-container-servlet</artifactId> <version>3.0.4</version> </dependency> <dependency> <groupId>org.glassfish.jersey.media</groupId> <artifactId>jersey-media-json-jackson</artifactId> <version>3.0.4</version> </dependency> <dependency> <groupId>org.glassfish.jersey.inject</groupId> <artifactId>jersey-cdi2-se</artifactId> <version>3.0.4</version> </dependency> <dependency> <groupId>org.jboss.weld.se</groupId> <artifactId>weld-se-core</artifactId> <version>4.0.3.Final</version> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-api</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-engine</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.2</version> </plugin> </plugins> </build> </project>

• HelloResource.java is a root resource class, which uses the following JAX-RS annotations to implement the RESTful web service:

  • The @Path annotation identifies the URI for accessing this resource, relative to the application root.

  • The @GET annotation indicates that the hello() method will process HTTP GET requests to the specified URI.

  • The @Produces annotation specifies the MIME media type that the method produces and returns.

  package com.example.restglassfishhelloworld; import jakarta.ws.rs.GET; import jakarta.ws.rs.Path; import jakarta.ws.rs.Produces; @Path("/hello-world") public class HelloResource { @GET @Produces("text/plain") public String hello() { return "Hello, World!"; } }
  package com.example.resttomcathelloworld; import jakarta.ws.rs.GET; import jakarta.ws.rs.Path; import jakarta.ws.rs.Produces; @Path("/hello-world") public class HelloResource { @GET @Produces("text/plain") public String hello() { return "Hello, World!"; } }

• HelloApplication.java is a subclass of javax.ws.rs.core.Application, which is used to configure the environment where the application runs REST resources defined in your resource classes. The @ApplicationPath annotation identifies the URL mapping for the application root (by default, it is set to /api).

  package com.example.restglassfishhelloworld; import jakarta.ws.rs.ApplicationPath; import jakarta.ws.rs.core.Application; @ApplicationPath("/api") public class HelloApplication extends Application { }
  package com.example.resttomcathelloworld; import jakarta.ws.rs.ApplicationPath; import jakarta.ws.rs.core.Application; @ApplicationPath("/api") public class HelloApplication extends Application { }

Configure the application server

Let IntelliJ IDEA know where the GlassFish Tomcat application server is located.

1. Press Ctrl+Alt+S to open settings and then select Build, Execution, Deployment | Application Servers.

2. Click and select Glassfish Server Tomcat.

3. Specify the path to the GlassFish Tomcat server install location. IntelliJ IDEA detects and sets the name and version appropriately.

   

   

Create a run configuration

IntelliJ IDEA needs a run configuration to build the artifacts and deploy them to your application server.

1. In the main menu, go to Run | Edit Configurations.

2. In the Run/Debug Configurations dialog, click , expand the Glassfish Server Tomcat Server node, and select Local.

3. Fix any warnings that appear at the bottom of the run configuration settings dialog.

   

   Most likely, you will need to fix the following:

   • On the Server tab, set the Server Domain to domain1.

   • On the Deployment tab, add the artifact that you want to deploy: RestGlassfishHelloWorld:war exploded RestTomcatHelloWorld:war exploded

4. On the Server tab, set the URL to point to the root resource:

   http://localhost:8080/RestGlassfishHelloWorld-1.0-SNAPSHOT/api/hello-world
   http://localhost:8080/RestTomcatHelloWorld_war_exploded/api/hello-world

   

   

5. Click OK to save the run configuration.

6. To run the configuration, press Alt+Shift+F10 and select the created application server configuration.

   Alternatively, if you have your run configuration selected in the main toolbar at the top, you can click in the main toolbar or press Shift+F10 to run it.

This run configuration builds the artifacts, then starts the GlassFish Tomcat server, and deploys the artifacts to the server. You should see the corresponding output in the Services tool window.

Once this is done, IntelliJ IDEA opens the specified URL in your web browser.

If not, try opening the URL yourself: http://localhost:8080/RestGlassfishHelloWorld-1.0-SNAPSHOT/api/hello-world http://localhost:8080/RestTomcatHelloWorld_war_exploded/api/hello-world