Welcome to the fifth lesson of our course on building an image generation service with Java! In our previous lessons, we've built several key components of our application: the PromptManager for formatting user inputs, the ImageManager for storing and processing images, the ImageGeneratorService for connecting to Google's Gemini API, and, most recently, the ImageGeneratorController, which handles input validation and response formatting.

Now it's time to bring everything together by creating a Java web application that will expose our functionality through HTTP endpoints. This is the final piece of our backend architecture that will allow users to interact with our image generation service through a web interface.

In the previous lesson, we built the ImageGeneratorController, which acts as an intermediary between our service layer and the API endpoints we'll create today. The controller handles the business logic of validating inputs, calling the appropriate service methods, and formatting responses. Now, we'll create the web endpoints that will receive HTTP requests from clients and pass them to our controller.

Our Java web API will have three main endpoints:

1. An endpoint to serve the main response at /
2. An endpoint to handle image generation requests
3. An endpoint to retrieve all previously generated images

By the end of this lesson, you'll have a complete Java web API that integrates with our controller, providing a clean interface for clients to generate and retrieve images.

Let's start by setting up our Java web application. In this lesson, we'll use Spring Boot, a popular Java framework for building web applications. Spring Boot simplifies the process of creating stand-alone, production-grade web services with minimal configuration.

To include Spring Boot in your Gradle project, add the following to your build.gradle file:

This configuration applies the Spring Boot plugin and includes the necessary dependencies for building a web application with Spring Boot.

Create the main application class in src/main/java/com/codesignal/Main.java:

This class uses the @SpringBootApplication annotation to enable Spring Boot's auto-configuration and component scanning. The main method starts the embedded web server and launches the application.

Before defining endpoints, it's important to understand two common Spring annotations:

• @Controller is typically used for MVC applications that render views such as HTML templates.
• @RestController is shorthand for @Controller + @ResponseBody, which means returned values are written directly to the HTTP response body.

That distinction matters because a plain String returned from a @Controller method is usually treated as a view name, not as response text. In this unit, we want our root route to return a plain string and our API endpoints to return JSON, so @RestController is the better fit.

We'll start by creating the Spring-aware ImageGeneratorController that contains our application logic and the root endpoint. This is the same controller role we introduced in the previous unit, now registered as a Spring bean so the web layer can use it directly.

A few important notes about this class:

• The root route / is mapped directly with @GetMapping("/").

Now that we have our Spring-managed application controller, let's define the endpoints that will handle client requests.

In Spring Boot, endpoints are defined in controller classes using annotations such as @RestController, @GetMapping, and @PostMapping. These annotations map HTTP requests to Java methods, allowing you to handle different types of requests and URLs.

We'll use a separate ImageGeneratorRestController to expose the /api routes and delegate to the ImageGeneratorController we just built.

Let's define the endpoint for generating images:

Here, we use the @RestController annotation to indicate that this class will handle REST API requests and return JSON responses. The @RequestMapping("/api") annotation sets a base path for all endpoints in this class.

The @PostMapping("/generate_image") annotation maps POST requests to /api/generate_image to the generateImage() method. The @RequestBody annotation tells Spring to parse the incoming JSON request body into a Map<String, String>. We extract both and from the map and pass them to our 's method, which handles the business logic and returns a response.

Next, let's define the endpoint for retrieving all previously generated images:

This method is mapped to GET requests at /api/get_images using the @GetMapping annotation. It simply calls the getImages() method of our controller, which retrieves all stored images and returns them as a JSON response.

With these three endpoints, our Java web API provides a complete interface for clients to interact with our image generation service. Clients can confirm the application is running, generate new images, and retrieve previously generated ones.

Now that we have our Spring Boot application and endpoints defined, let's configure the server to run our application.

By default, Spring Boot uses an embedded Tomcat server that listens on port 8080. If you want to change the port or other server settings, you can do so in the src/main/resources/application.properties file:

• server.port=3000 tells Spring Boot to listen on port 3000 for incoming requests.
• server.address=0.0.0.0 makes the server accessible on all network interfaces.

Once the application is running, you should see output similar to:

You can now access your application by opening a web browser and navigating to http://localhost:3000/.

In this lesson, we've built a complete Java web API using Spring Boot that integrates with our ImageGeneratorController to provide a web interface for our image generation service. Let's review what we've accomplished:

1. We set up a Spring Boot application with the necessary configuration, including port and host settings.
2. We clarified the difference between @Controller and @RestController, and used @RestController because this unit returns response bodies rather than rendered templates.
3. We created an ImageGeneratorController that handles the root route plus the core image-generation and retrieval logic.
4. We implemented a POST endpoint for generating images, which extracts user_input and aspect_ratio from the request and passes them to our controller.
5. We set up a GET endpoint for retrieving all previously generated images.
6. We configured the embedded web server to run on a specific port and listen on all network interfaces.

Our Java web API now provides a complete interface for clients to interact with our . The endpoints receive requests, extract the necessary data, and pass it to our controller, which handles the business logic of validating inputs, applying a default aspect ratio when needed, calling the appropriate service methods, and formatting responses.