Architectural Overview

Relevant source files

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

• 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
• README.adoc

This document provides an architectural overview of the gs-rest-service project. The project is a simple, self-contained RESTful web service built using the Spring Framework. Its primary function is to expose an HTTP endpoint that returns a "Hello, World" style greeting in JSON format. The service is designed to be straightforward, demonstrating the core principles of building a REST API with Spring Boot.

The architecture is centered around a single controller that handles incoming HTTP requests, a data model for the JSON response, and a main application class that bootstraps the entire service. It leverages Spring Boot's auto-configuration to minimize manual setup, providing an embedded web server and automatic JSON serialization.

Sources: README.adoc

Application Entry Point

The application is bootstrapped by the RestServiceApplication class. This class contains the main method, which is the standard entry point for a Java application.

The class is annotated with @SpringBootApplication, a convenience annotation that adds:

• @Configuration: Tags the class as a source of bean definitions for the application context.
• @EnableAutoConfiguration: Tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings.
• @ComponentScan: Tells Spring to look for other components, configurations, and services in the com.example.restservice package.

The SpringApplication.run() method launches the application, which includes starting the embedded web server (Tomcat by default).

// complete/src/main/java/com/example/restservice/RestServiceApplication.java:6-12
@SpringBootApplication
public class RestServiceApplication {

	public static void main(String[] args) {
		SpringApplication.run(RestServiceApplication.class, args);
	}

}

Sources: complete/src/main/java/com/example/restservice/RestServiceApplication.java:6-12

Core Components and Request Flow

The service consists of two primary Java classes: GreetingController and Greeting. The GreetingController handles the request logic, while Greeting serves as the data model for the response.

The following diagram illustrates the high-level request flow.

This diagram shows a client making a GET request to the /greeting endpoint, which is handled by the GreetingController. The controller creates a Greeting object, which is then automatically serialized into a JSON response and sent back to the client.

Sources: README.adoc, complete/src/main/java/com/example/restservice/GreetingController.java

REST Controller

HTTP requests are handled by GreetingController. This class is marked with the @RestController annotation, which identifies it as a controller where every method returns a domain object instead of a view. This is a shorthand for including both @Controller and @ResponseBody.

Key features of the controller:

• Stateful Counter: It maintains an AtomicLong counter to provide a unique ID for each greeting. This instance is shared across multiple requests.
• Request Mapping: The greeting() method is mapped to handle HTTP GET requests for the /greeting path.

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

Data Model

The Greeting class is a Java record that models the data returned by the service. A record is a concise way to create immutable data-carrier classes.

Field	Type	Description
id	long	A unique identifier for the greeting.
content	String	The textual representation of the greeting.

The Greeting object is automatically converted to JSON in the HTTP response by the Jackson 2 library, which is included by default with the spring-boot-starter-web dependency.

// complete/src/main/java/com/example/restservice/Greeting.java:3
public record Greeting(long id, String content) { }

Sources: complete/src/main/java/com/example/restservice/Greeting.java:3, README.adoc

The relationship between the controller and the model is straightforward: the controller creates and returns an instance of the model.

This class diagram shows that GreetingController has a dependency on Greeting, as its greeting method returns a Greeting object.

Sources: complete/src/main/java/com/example/restservice/GreetingController.java, complete/src/main/java/com/example/restservice/Greeting.java

API Endpoint: /greeting

The service exposes a single API endpoint.

Property	Value
Path	/greeting
HTTP Method	GET
Response Format	JSON

Request Parameters

Parameter	Type	Description	Default Value
name	String	An optional name to include in the greeting message.	"World"

The @GetMapping("/greeting") annotation maps the greeting() method to GET requests for /greeting. The @RequestParam annotation binds the value of the name query string parameter to the name method parameter. If the name parameter is absent, the defaultValue of "World" is used.

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

Sequence Diagram

The following sequence diagram details the interactions when a client calls the /greeting endpoint.

This diagram shows the flow from the initial client request through the Spring Framework to the GreetingController, the instantiation of the Greeting object, and the final JSON response back to the client.

Sources: complete/src/main/java/com/example/restservice/GreetingController.java:15-17

Project Dependencies

The project is built using Apache Maven. The core functionality is enabled by the dependencies defined in pom.xml.

The most significant dependency is spring-boot-starter-web, which is a "starter" that bundles several key libraries:

• Spring MVC framework for building web applications and REST APIs.
• An embedded web server (Tomcat by default).
• Jackson for automatic JSON serialization/deserialization.

<!-- complete/pom.xml:20-24 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

The project also includes spring-boot-starter-test for testing support.

Sources: complete/pom.xml:20-24, 26-30

Testing

The application includes integration tests for the GreetingController. The GreetingControllerTests class uses Spring's testing framework to verify the behavior of the REST endpoint without needing to run a full server.

Key annotations and components used for testing:

• @SpringBootTest: Loads the full application context for an integration test.
• @AutoConfigureMockMvc: Configures a MockMvc instance, which allows for sending mock HTTP requests to the controller.

The tests verify two scenarios:

1. A request to /greeting without a name parameter returns the default message "Hello, World!".
2. A request to /greeting with a name parameter (e.g., ?name=Spring Community) returns a tailored message.

// complete/src/test/java/com/example/restservice/GreetingControllerTests.java:40-43
@Test
public void paramGreetingShouldReturnTailoredMessage() throws Exception {
    this.mockMvc.perform(get("/greeting").param("name", "Spring Community"))
            .andDo(print()).andExpect(status().isOk())
            .andExpect(jsonPath("$.content").value("Hello, Spring Community!"));
}

The jsonPath expression $.content is used to inspect the content field of the JSON response and assert its value.

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