Home

Relevant source files

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

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

This project, gs-rest-service, is a simple "Hello, World" RESTful web service built using the Spring Framework. It is designed to demonstrate the basic principles of creating a REST API with Spring Boot. The service exposes a single endpoint, /greeting, which accepts HTTP GET requests and returns a JSON object representing a greeting.

The core functionality includes handling optional request parameters to customize the greeting message and maintaining a request counter. The application is self-contained and can be run as a standalone JAR file, leveraging Spring Boot's auto-configuration and embedded server capabilities.

Sources: README.adoc

System Architecture

The application follows a standard Spring Boot architecture for web services. It consists of three main components: an application entry point, a resource controller, and a resource representation class (data model).

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

Component Overview

The diagram below illustrates the primary Java classes and their roles within the service.

This diagram shows that RestServiceApplication starts the application, which in turn registers the GreetingController. The controller then creates Greeting objects for responses.

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

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.

// 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);
	}

}

The @SpringBootApplication annotation enables auto-configuration, component scanning, and other Spring Boot features. The SpringApplication.run() method launches the application, starts the embedded web server, and initializes the Spring application context.

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

API Endpoint: /greeting

The service exposes a single HTTP endpoint to provide greetings.

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

Endpoint Details

Property	Value	Description
Path	/greeting	The URL path for the endpoint.
HTTP Method	GET	The endpoint responds to HTTP GET requests.
Response Format	JSON	The response body is a JSON object.

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

Request Parameters

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

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

Request Flow

The following sequence diagram illustrates the process of handling a GET /greeting?name=User request.

This diagram shows a client request being routed by the Spring Framework to the GreetingController, which then creates a Greeting object and returns it. The framework handles the final JSON serialization.

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

Controller Implementation

The GreetingController class handles incoming web requests.

// complete/src/main/java/com/example/restservice/GreetingController.java:8-16
@RestController
public class GreetingController {

	private static final String template = "Hello, %s!";
	private final AtomicLong counter = new AtomicLong();

	@GetMapping("/greeting")
	public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
		return new Greeting(counter.incrementAndGet(), String.format(template, name));
	}
}

• @RestController: Marks the class as a controller where every method returns a domain object instead of a view. It's a shorthand for @Controller and @ResponseBody.
• @GetMapping("/greeting"): Maps HTTP GET requests for /greeting to the greeting() method.
• @RequestParam: Binds the value of the name query string parameter to the name method parameter. If the parameter is absent, it uses the defaultValue "World".
• AtomicLong counter: A thread-safe counter to generate unique id values for each request.

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

Data Model

The data model for the response is defined by the Greeting class.

Greeting Resource Representation

The Greeting class is a Java record, which is a concise way to create immutable data carrier classes.

// complete/src/main/java/com/example/restservice/Greeting.java:3
package com.example.restservice;

public record Greeting(long id, String content) { }

This record automatically defines private final fields for id and content, a canonical constructor, and accessor methods.

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

Fields

Field	Type	Description
id	long	A unique identifier for the greeting, incremented with each request.
content	String	The textual representation of the greeting message.

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

Class Diagram

The relationship between the controller and the data model is straightforward.

This diagram shows that the GreetingController creates instances of the Greeting record.

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

Build & Dependencies

The project is configured as a Maven project and relies on Spring Boot starters to manage dependencies.

Sources: complete/pom.xml

Key Dependencies

The pom.xml file defines the project's dependencies.

Group ID	Artifact ID	Description
org.springframework.boot	spring-boot-starter-web	Provides dependencies for building web applications, including RESTful applications using Spring MVC. It includes an embedded Tomcat server and the Jackson library for JSON processing.
org.springframework.boot	spring-boot-starter-test	Provides dependencies for testing Spring Boot applications with libraries like JUnit 5, Mockito, and Spring Test.

Sources: complete/pom.xml:19-29

Testing

The application includes integration tests for the GreetingController. The tests are located in GreetingControllerTests.java and use MockMvc to perform requests against the controller without needing to start a full HTTP server.

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

Test Cases

1. noParamGreetingShouldReturnDefaultMessage(): This test performs a GET request to /greeting without any parameters. It asserts that the HTTP status is 200 OK and the content field in the JSON response is "Hello, World!".

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

2. paramGreetingShouldReturnTailoredMessage(): This test performs a GET request to /greeting with the name parameter set to "Spring Community". It asserts that the status is 200 OK and the content field is "Hello, Spring Community!".

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