Project Goals

Relevant source files

The following files were used as context for generating this wiki page:

• README.adoc
• complete/src/main/java/com/example/restservice/GreetingController.java
• complete/src/main/java/com/example/restservice/Greeting.java
• complete/src/main/java/com/example/restservice/RestServiceApplication.java
• complete/pom.xml
• complete/src/test/java/com/example/restservice/GreetingControllerTests.java

The primary goal of this project is to create a simple, "Hello, World" RESTful web service using the Spring Framework. The service is designed to demonstrate the fundamental principles of building a web service with Spring, including handling HTTP requests, managing request parameters, and returning JSON responses. It serves as a foundational guide for developers new to Spring or REST services.

The project builds a service that exposes a single endpoint, /greeting. This endpoint accepts HTTP GET requests and returns a JSON object representing a greeting. The content of the greeting can be customized via a query parameter. The entire application is packaged as a standalone executable JAR, runnable with a simple java -jar command, showcasing the convenience of Spring Boot.

Sources: README.adoc:5-7, complete/src/main/java/com/example/restservice/RestServiceApplication.java

Core Functionality: RESTful Web Service

The central objective is to build a service that handles HTTP GET requests at http://localhost:8080/greeting. The service responds with a JSON representation of a greeting.

Sources: README.adoc:7-8

API Endpoint

The service exposes one primary endpoint.

Method	Path	Description
GET	/greeting	Returns a JSON greeting. Accepts an optional name query parameter to customize the greeting's content.

Sources: README.adoc:7-8, complete/src/main/java/com/example/restservice/GreetingController.java:13-16

Request Parameter

The /greeting endpoint can be customized with an optional query parameter.

Parameter	Type	Default Value	Description
name	String	"World"	Overrides the default name in the greeting's content.

This is handled by the @RequestParam annotation in the GreetingController.

// complete/src/main/java/com/example/restservice/GreetingController.java:14
public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
    // ...
}

Sources: README.adoc:15-17, complete/src/main/java/com/example/restservice/GreetingController.java:14

JSON Response Structure

The service returns a JSON object that models the greeting. The structure is defined by the Greeting record class.

Field	Type	Description
id	long	A unique identifier for the greeting, which increments on each request.
content	String	The textual representation of the greeting.

An example response for http://localhost:8080/greeting?name=User is:

{
    "id": 1,
    "content": "Hello, User!"
}

The Greeting object is automatically marshaled into JSON by the Jackson 2 library, which is included by default with the spring-boot-starter-web dependency.

Sources: README.adoc:10-13, README.adoc:20-23, README.adoc:42-48, complete/src/main/java/com/example/restservice/Greeting.java:3

Architecture and Components

The project's architecture is simple and follows standard Spring Boot conventions, consisting of a main application class, a controller, and a data transfer object (record).

This diagram shows the key classes and their roles in the application.

Components

• RestServiceApplication: The main class that bootstraps the Spring Boot application. The @SpringBootApplication annotation enables auto-configuration and component scanning.
  Sources: complete/src/main/java/com/example/restservice/RestServiceApplication.java
• GreetingController: A REST controller identified by the @RestController annotation. It handles incoming HTTP requests. The greeting() method is mapped to the /greeting path for GET requests via the @GetMapping annotation.
  Sources: complete/src/main/java/com/example/restservice/GreetingController.java:9,13
• Greeting: A Java record class that serves as a resource representation model for the greeting data. Instances of this class are converted to JSON for the HTTP response.
  Sources: complete/src/main/java/com/example/restservice/Greeting.java:3

Request Handling Flow

The following sequence diagram illustrates the flow of a GET /greeting request.

This flow demonstrates how an incoming request is mapped to a controller method, processed, and how the return object is automatically converted to a JSON response.

Sources: README.adoc:60-91, complete/src/main/java/com/example/restservice/GreetingController.java:13-16

Build and Dependencies

The project is configured to be built using either Maven or Gradle. The core dependency is spring-boot-starter-web, which provides all necessary components for building a web application, including an embedded Tomcat server and the Jackson library for JSON processing.

Key Dependencies (from pom.xml)

Group ID	Artifact ID	Scope	Description
org.springframework.boot	spring-boot-starter-web		Starter for building web applications, including RESTful, using Spring MVC.
org.springframework.boot	spring-boot-starter-test	test	Starter for testing Spring Boot applications.

The project uses Java 17 and Spring Boot 3.3.0.

Sources: complete/pom.xml:9,18,23,29

Testing

The project includes tests to verify the controller's behavior. The GreetingControllerTests class uses MockMvc to perform requests against the /greeting endpoint and assert the responses.

• noParamGreetingShouldReturnDefaultMessage(): Tests the endpoint without the name parameter, expecting the default "Hello, World!" message.
• paramGreetingShouldReturnTailoredMessage(): Tests the endpoint with a name parameter, expecting a customized message.

// complete/src/test/java/com/example/restservice/GreetingControllerTests.java:39-42
@Test
public void noParamGreetingShouldReturnDefaultMessage() throws Exception {
    this.mockMvc.perform(get("/greeting")).andDo(print()).andExpect(status().isOk())
            .andExpect(jsonPath("$.content").value("Hello, World!"));
}

Sources: complete/src/test/java/com/example/restservice/GreetingControllerTests.java:37-51