Write your web service

This guide shows how to write a Java web service to run in the App Engine standard environment. To learn more about the Java runtime and how it works, see Java Runtime Environment.

Before you begin

If you haven't already:

1. Install the latest version of the Java Development Kit (JDK) for the App Engine runtime version you plan to use.
2. Download and install Apache Maven to build, run, and deploy the sample app.

Key points

• App Engine starts your application by uploading an executable JAR application.
• Your application must have a main class that starts a web server which responds to HTTP requests on the port specified by the PORT environment variable, typically 8080.
• You need an app.yaml file to deploy your service to App Engine.
• You can use dependencies by listing them in your pom.xml file. For more information, see Using Java libraries.

Create a main class

The core of your web service is the HTTP server. The sample code in this guide uses the Spring Boot framework to handle HTTP requests, but you are free to use a web framework of your choice.

1. Generate a Spring Boot project for Java that uses the Maven build system and contains the Spring Web dependency. To get started, click the following link:

   Go to Spring Initializr

2. In Spring Initializer, click the Generate button to generate and download your project.

3. In the downloaded project, edit the file springboot/src/main/java/com/example/appengine/springboot/DemoApplication.java to add some java imports and a REST hello handler:

   package com.example.appengine.springboot;
   import org.springframework.boot.SpringApplication;
   import org.springframework.boot.autoconfigure.SpringBootApplication;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RestController;
   @SpringBootApplication
   @RestController
   public class DemoApplication {
   public static void main(String[] args) {
   SpringApplication.run(DemoApplication.class, args);
   }
   @GetMapping("/")
   public String hello() {
   return "Hello world!";
   }
   }
   

   The modified class is a controller that starts Spring Boot's embedded Tomcat server and responds to GET requests at the root path ('/') with the text "Hello world!"

Run the server locally

To run the server locally:

1. Start a local web server using the Spring Boot Maven plugin.

   mvn spring-boot:run
   

2. In your web browser, enter the following address:
   http://localhost:8080

The Hello World message from the sample app displays on the page. In your terminal window, press Ctrl+C to exit the web server.

Create the app.yaml file

To specify settings for your app in the App Engine runtime environment:

1. Create a file named app.yaml in the following directory:
   springboot/src/main/appengine/

2. Add the following contents to the file:

   Java 21

   runtime: java21
   

   The app.yaml file can also specify network settings, scaling settings, and more. For more information, see the app.yaml reference.

If you used the Spring Initializr link above, you should now have a file structure like the following:

• springboot/
  • pom.xml
  • src/main/
    • appengine/
      • app.yaml
    • java/com/example/appengine/springboot/
      • DemoApplication.java

You can also add in the project pom.xml the Maven plugin that allows deployment of the application:

            <plugin>
                <groupId>com.google.cloud.tools</groupId>
                <artifactId>appengine-maven-plugin</artifactId>
                <version>2.8.1</version>
                <configuration>
                    <projectId>YOUR_PROJECT_NAME</projectId>
                    <version>YOUR_VERSION</version>
                    <promote>false</promote>
                </configuration>
            </plugin>

Next steps

Now that you've created a simple Java web server that listens to the correct port and you've specified the runtime in an app.yaml file, you're ready to deploy your service on App Engine.