Milestone [1] Complete Hello World API Migration to Spring Boot

[mcode-app]

View Milestone

Table of Contents

• Status
• Feature Overview
• Testing
• Architecture
• Suggested Order of Review

Status

All tasks in the milestone were successfully completed.

Feature Overview

This milestone delivers a complete migration of the Flask-based REST API to Spring Boot. The migrated application provides a single GET endpoint at the root path (/) that accepts an optional name query parameter and returns a JSON greeting message.

End users (API clients) can:

• Send GET requests to http://localhost:3000/ to receive {"message": "Hello World!"}
• Send GET requests with a custom name parameter (e.g., http://localhost:3000/?name=Alice) to receive {"message": "Hello Alice!"}
• The application automatically trims whitespace from the name parameter, matching the behavior of the original Python implementation

The migrated application reads its server port from the SERVER_PORT environment variable (defaulting to 3000) and can be deployed as a standalone executable JAR file using java -jar target/hello-world-api-1.0.0.jar.

Testing

Automated Testing

No automated tests were included in the source application. The milestone focused on functional equivalence through manual verification.

Manual Testing

Reviewers can verify the functionality by following these steps:

1. Build the application:

   cd /l2l/dst/hello-world-api/
   mvn clean package -DskipTests

2. Run the application:

   java -jar target/hello-world-api-1.0.0.jar

3. Test the endpoint:

   • Default greeting: curl http://localhost:3000/ should return {"message":"Hello World!"}
   • Custom name: curl http://localhost:3000/?name=Alice should return {"message":"Hello Alice!"}
   • Whitespace trimming: curl "http://localhost:3000/?name=%20Bob%20" should return {"message":"Hello Bob!"} (spaces removed)

4. Test port configuration:

   • Without SERVER_PORT set: application should listen on port 3000 (not Spring Boot's default 8080)
   • With SERVER_PORT set: SERVER_PORT=8080 java -jar target/hello-world-api-1.0.0.jar should listen on port 8080

All responses should match the Python implementation exactly in structure and content.

Architecture

Overview

graph TB
    Client[HTTP Client]
    
    subgraph SpringBoot["Spring Boot Application"]
        Controller[HelloController<br/>REST Controller]
        Model[HelloResponse<br/>Record Class]
        Config[application.properties<br/>Port Configuration]
        AppEntry[Application<br/>Entry Point]
        Tomcat[Embedded Tomcat<br/>Web Server]
        Jackson[Jackson JSON<br/>Serializer]
        
        AppEntry -.->|Bootstraps| SpringBoot
        Config -.->|Configures| Tomcat
        Tomcat -->|Routes Request| Controller
        Controller -->|Creates| Model
        Model -->|Serialized by| Jackson
    end
    
    Client -->|GET /?name=X| Tomcat
    Jackson -->|JSON Response| Client
    
    style Controller fill:#90EE90
    style Model fill:#90EE90
    style Config fill:#90EE90
    style AppEntry fill:#90EE90
    style Tomcat fill:#90EE90
    style Jackson fill:#90EE90
    
    style SpringBoot fill:#f9f9f9,stroke:#333,stroke-width:2px
    
    subgraph Legend
        New[New/Modified Module]
        style New fill:#90EE90
    end

Loading

Changes

Build Configuration (pom.xml:1-45)

Maven POM file establishing the Spring Boot project structure with Spring Boot 3.2.1 parent POM, Java 17 target version, and spring-boot-starter-web dependency. Configures the spring-boot-maven-plugin to package the application as an executable JAR file. Replaces the Python requirements.txt with Maven-based dependency management.

Application Entry Point (Application.java:1-12)

Main application class annotated with @SpringBootApplication that serves as the entry point for the Spring Boot application. The main method invokes SpringApplication.run() to bootstrap the embedded Tomcat server and Spring context. Replaces the Python if __name__ == "__main__" block and Flask's app.run() initialization.

REST Controller (HelloController.java:1-16)

REST controller handling GET requests to the root path. Uses @RequestParam with defaultValue = "World" for declarative parameter extraction, applies String.trim() to match Python's strip() behavior, and returns a HelloResponse object that Jackson automatically serializes to JSON. Replaces the Flask @app.route("/") handler function.

Response Model (HelloResponse.java:1-4)

Java record class representing the JSON response structure with a single message field. Provides immutability and concise syntax while ensuring type-safe response construction. Jackson serializes this to {"message": "..."} format. Replaces the Python dictionary returned by jsonify().

Server Configuration (application.properties:1-2)

Spring Boot configuration file using the server.port=${SERVER_PORT:3000} pattern to read the server port from the SERVER_PORT environment variable with a default value of 3000. Replaces the Python os.environ.get('SERVER_PORT', 3000) approach with Spring's property placeholder mechanism.

Project Metadata (.gitignore:1-39)

Standard Java/Maven .gitignore file to exclude build artifacts (target/), IDE files, and generated content from version control.

Design Decisions

Query Parameter Handling Strategy

The implementation uses Spring Boot's @RequestParam annotation with the defaultValue attribute for declarative parameter handling. This approach was selected over manual null-checking or Optional<String> patterns because it provides the most idiomatic Spring Boot solution with clear declarative intent. The annotation directly maps the query parameter to the method argument while handling default values transparently.

Application Configuration Management

Server port configuration was implemented using application.properties with the server.port=${SERVER_PORT:3000} property placeholder pattern. This approach leverages Spring Boot's built-in server configuration mechanism rather than custom configuration classes or direct environment variable access. It ensures seamless integration with Spring Boot's embedded Tomcat setup and follows the framework's standard conventions for server configuration.

Response Structure and Serialization

A Java record class (HelloResponse) was chosen to represent the JSON response structure. Records provide immutability, concise syntax, and automatic generation of constructors and accessors. This approach offers type safety and clear response schema definition while allowing Jackson to handle JSON serialization automatically. The record pattern scales better than simple Maps for applications with multiple endpoints and complex response structures.

String Whitespace Processing

Java's String.trim() method was selected to replicate Python's strip() behavior for removing leading and trailing whitespace. Both methods handle ASCII whitespace identically, ensuring functional equivalence for the expected input domain of the API.

Suggested Order of Review

1. pom.xml - Start with the build configuration to understand project dependencies, Spring Boot version, and packaging setup
2. src/main/resources/application.properties - Review server port configuration and environment variable integration
3. src/main/java/com/example/helloworldapi/Application.java - Examine the application entry point and Spring Boot initialization
4. src/main/java/com/example/helloworldapi/model/HelloResponse.java - Review the response model structure before seeing how it's used
5. src/main/java/com/example/helloworldapi/controller/HelloController.java - Examine the REST controller implementation, parameter handling, and response construction
6. .gitignore - Review excluded files and directories for the Java/Maven project