gs-rest-service: the Spring guide that builds a JSON endpoint from scratch

What the guide builds

The gs-rest-service guide walks you through the process of creating a Hello World RESTful web service with Spring, and the service it produces is deliberately small.

It accepts HTTP GET requests at a greeting path on the local server and responds with a JSON representation of a greeting.

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

There is one optional input. A name parameter in the query string overrides the default of World.

http://localhost:8080/greeting?name=User

And the response reflects the override, with the content changing while the identifier stays the same.

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

That is the whole application, and the point of the guide is not the application. It is that every piece of it is small enough to show completely, and every annotation involved is explained in the text rather than left to the reader's memory of the framework. The guide is published on the Spring site as part of the guides series, and the repository is the source of that page, with the project identifier and a table of contents that the site renders.

Starting from Spring Initializr

The setup path is the standard one for the Spring ecosystem, and the guide gives both the automatic and the manual route.

The fast route is a link that pre-fills the Initializr with the right choices, a Gradle project in Java, packaged as a jar, with the group and package names set and the web dependency selected, so you click Generate and download a ZIP that is already configured to fit the examples in the tutorial.

The manual route is spelled out step by step. Navigate to the Initializr, which pulls in the dependencies you need and does most of the setup for you. Choose either Gradle or Maven and the language you want to use. Type rest-service in the Artifact field. Select the Spring Web dependency under Dependencies. Then click Generate and download the ZIP, which is an archive of a web application configured with your choices.

Two notes come with it. If your IDE has the Initializr integration, you can do the whole thing from the IDE, and you can also fork the project from GitHub and open it in an IDE or another editor.

The choice of the web dependency is the one decision that matters, because it is what puts a servlet container and Jackson on the classpath. The guide calls out later that Jackson is included by default by the web starter, and that is the reason the JSON conversion works without a line of conversion code.

The resource representation, and why there is no conversion code

The guide asks you to think about the service interactions before writing anything, and the shape of the contract is spelled out. The service handles GET requests for the greeting path with an optional name parameter, and it should return a 200 OK response with JSON in the body.

The representation has two fields. The id is a unique identifier for the greeting, and the content is the textual representation of the greeting.

To model it, you create a resource representation class, and the guide is careful to offer both languages, a Java record class in the source tree, or a Kotlin data class in the equivalent Kotlin source tree. The controller then returns an instance of that class and the framework does the rest.

The note attached to that step is the one that saves the most time. The application uses the Jackson JSON library to automatically marshal instances of the type into JSON, and Jackson is included by default by the web starter.

So the record is the entire model. There is no entity class, no DTO, no serializer and no getter, because a record carries its own data and the framework has a converter for it. That is a design decision the guide is teaching as much as an API, and the reason it starts with the response body rather than with the controller is that the response body is the contract.

The controller, annotation by annotation

The guide says that in Spring's approach to building RESTful web services, HTTP requests are handled by a controller, and these are identified by the RestController annotation. The controller class handles the GET requests for the greeting path by returning a new instance of the Greeting class.

The controller is concise, and the guide says there is plenty going on under the hood, then breaks it down.

The GetMapping annotation ensures that HTTP GET requests to the path are mapped to the method. There are companion annotations for the other verbs, such as PostMapping for POST, and there is a RequestMapping annotation that they all derive from, which can also serve as a synonym, for example with the method set to GET.

The RequestParam annotation binds the value of the name query string parameter into the method parameter, and if the name parameter is absent from the request, the default value of World is used.

The method body then creates and returns a new Greeting object with the id and the content attributes, based on the next value from the counter, and formats the given name using the greeting template.

Two details in that description are worth dwelling on. The default value on the annotation is what makes the optional parameter optional, and it is a declaration rather than a null check in the body, which is the difference between a contract that says the parameter may be absent and code that defends against it.

What changes without a view layer

The guide draws the distinction it exists to teach, and it does so in a paragraph.

A key difference between a traditional MVC controller and the RESTful web service controller is the way the HTTP response body is created. Rather than relying on a view technology to perform server side rendering of the greeting data to HTML, the controller populates and returns a Greeting object, and the object data is written directly to the HTTP response as JSON.

The annotation makes that possible. The RestController annotation marks the class as a controller where every method returns a domain object instead of a view, and it is shorthand for including both the Controller annotation and the ResponseBody annotation.

And the conversion is automatic. The Greeting object must be converted to JSON, but thanks to Spring's HTTP message converter support you need not do that conversion manually. Because Jackson is on the classpath, the Jackson JSON message converter is automatically chosen to convert the Greeting instance to JSON.

So the three moving parts are: the record holds the data, the annotation says the method returns data rather than a view, and the converter on the classpath decides the format. A reader who knows those three can read any Spring controller, and a reader who does not will usually mistake the missing view layer for a missing piece of configuration.

The repository layout, and the two languages

The repository is organised around the two axes the guide supports, and the directory names make the structure obvious.

There is an initial directory and a complete directory for the Java version, and an initial-kotlin and a complete-kotlin for the Kotlin version. The initial directories hold the state after the setup step, and the complete ones hold the finished application, which is what lets the site render the same code twice, once per language.

The rendering mechanism explains the rest of the layout. The guide is written in AsciiDoc, and the code listings in the source are not pasted in. They are include directives that pull the file from the complete directory at build time, with the Java listing marked as primary and the Kotlin one as secondary, so the site shows the Java version by default and offers the Kotlin version as an alternative.

That design has an obvious consequence for a contributor. The code in the guide is the code in the repository, so there is no chance of the two drifting apart, and a change to the example is a change to the rendered page. The corollary is that the guide cannot show code that is not in the repository, which is why the JSON responses appear as literal listings while the Java and Kotlin classes are pulled in.

There is also a test directory, a contributing document, a licence file for the code and a separate licence file for the writing, which is the usual split when a guide's text and its sample code are licensed differently. The project identifier and the icons and source highlighter settings are declared in the header, which are metadata for the site that renders it.

What this guide is for

The guide occupies a specific place in the Spring documentation and it is worth being clear about that place.

It is a first service. It starts from a generated project and ends with one endpoint that returns a JSON object, and along the way it names the annotations involved and says what each one does. The prerequisites and the section on how to complete the guide are pulled in from a shared macros repository, which is how the Spring guides keep the boilerplate consistent across hundreds of pages.

What it is not is a template for a production service. There is no persistence, no authentication, no error handling, no validation, no pagination, no configuration beyond the generated defaults, and the only test is the one the project generator creates. A reader who copies it into a real project gets the shape of a Spring web service and none of the parts that make one safe.

That is the right scope for a tutorial, and the guide is clear that it is a first step. Its value is in the explanation of the response body, the record, the annotation and the converter, which together are the four things you have to understand before anything else in Spring web development makes sense.

The alternate route the guide mentions is worth repeating for anyone who wants the finished thing, since it saves the reading and the typing. You can fork the project from GitHub and open it in your IDE or another editor, and the complete directories are the finished application rather than a starting point.

Editorial conclusion

Adopt this guide as a walkthrough if you are learning Spring web development, because it explains the annotations in the order you need them and shows the response body you will actually get. Do not adopt it as a starting point for a production service, since it is a tutorial that ends at one endpoint with no persistence, no error handling and no tests beyond the generated ones. Before you start, note that the guide is maintained in AsciiDoc and pulls shared sections from another repository, so the parts you see here are the parts specific to this service.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. spring-guides/gs-rest-service on GitHub