tut-rest: the Spring guide that builds a payroll service into a hypermedia API

A guide repository, not an application you deploy

The repository spring-guides/tut-rest is the source for the Spring tutorial published at spring.io/guides/tutorials/rest/. Its content is an AsciiDoc document, README.adoc, with the usual guide metadata at the top: tags for rest, hateoas, hypermedia, security, testing and oauth, and a list of the Spring projects it draws on, namely spring-framework, spring-hateoas, spring-security and spring-security-oauth.

The interesting thing about the layout is that the prose and the code are separated. The top level contains the four solution modules, nonrest/, rest/, evolution/ and links/, along with pom.xml, the Maven wrapper scripts mvnw and mvnw.cmd, a .mvn/ directory, .travis.yml, and two licence files, LICENSE.code.txt and LICENSE.writing.txt. The guide text refers to source files with AsciiDoc include directives, so the code you read in the rendered tutorial is pulled from the modules in the same repository rather than being pasted into the document.

That is what makes the repository worth opening in a code editor rather than only in a browser. Each snippet in the guide points at a real file, and the four modules build on one another with the links module holding the final solution, so you can watch the same payroll service acquire REST semantics step by step. There are no GitHub releases and the last push was on 2026-09-01, which is normal for a guide whose history lives in the published page.

Four modules that add one REST constraint at a time

The guide is structured as four stages, and each one is a module in the solution repository. The headers map directly onto them.

The Story So Far corresponds to the nonrest module, and it is deliberately the least RESTful thing that can be built. The instruction is to start with the simplest construction possible, to the point where the concepts of REST can be left out entirely, and to add them later so the difference becomes visible. The completed GitHub repository separates the solution into four parts for that reason, rather than presenting a single finished project.

The second stage is Spring HATEOAS, in the rest module, which is where hypermedia enters. The third is Simplifying Link Creation, in the evolution module, and the fourth is Building links into your REST API, in the links module, which contains the final solution.

The progression matters more than the individual techniques. By the time you reach link creation, the reader already has a working application and can see what each added constraint buys, and the earlier module is still there as a reference for the plain version of the same domain. A reader who only wants the HATEOAS mechanics can jump to the rest module and the code there builds on the nonrest one, since the modules build on one another.

The domain model: an Employee entity and a repository interface

The example application is a payroll service that manages the employees of a company. Employee objects are stored in an H2 in-memory database and accessed through JPA, and the guide then wraps that in a Spring MVC layer so the data can be reached over the internet.

The Employee class is small and the guide is careful about why. It carries a JPA annotation that makes the object ready for storage in a JPA based data store. The id, name and role fields are attributes of the domain object, with id carrying further JPA annotations marking it as the primary key and letting the JPA provider populate it. A custom constructor exists for the case where a new instance is created before an id exists. That is the whole model, and it is enough for the guide to make its point about the persistence layer being unremarkable.

On top of it sits a repository interface that extends Spring Data JPA's JpaRepository, specifying Employee as the domain type and Long as the id type. Declaring that interface is what gives you record creation, updates, deletion and lookup, with paging and sorting where appropriate, because Spring Data synthesises the implementation from the conventions in the method names. The stated benefit is that you can sidestep data store specifics and work in domain terms instead.

The guide is also explicit that JPA is a choice, not a requirement: Spring Data MongoDB, Spring Data Cassandra and other implementations exist, and this tutorial sticks with JPA.

The argument for REST starts with what HTTP already gives you

Before any code, the guide makes its case for REST, and the argument is worth reading because it explains why the later code is shaped the way it is. REST is described as embracing the precepts of the web, including its architecture and benefits, and the author of REST, Roy Fielding, is noted as having been involved in a dozen specifications that govern how the web operates.

The benefits claimed are the features HTTP and its core protocol already provide: suitable actions such as GET, POST, PUT and DELETE, caching, redirection and forwarding, and security in the form of encryption and authentication. The guide calls these critical factors when building resilient services, and adds that the web is built out of many tiny specifications, an architecture that lets it evolve without getting bogged down in standards wars.

The consequences listed for REST APIs are backwards compatible APIs, evolvable APIs, scalable services, securable services, and a spectrum from stateless to stateful services. There is also a disclaimer that matters for anyone who treats REST as a checklist: REST is not a standard per se but an approach, a style, a set of constraints on an architecture.

The guide also acknowledges that how REST fits into the world of microservices is a much larger discussion, and deliberately stays out of it. The scope is building RESTful services.

Getting set up with Spring Initializr, Spring Web, JPA and H2

The prerequisites are modest: a text editor or IDE such as IntelliJ IDEA or VSCode, and Java 17 or later. The project itself is generated rather than cloned, which is the first practical step for a reader following along.

The instruction is to go to Spring Initializr and add three dependencies to a project: Spring Web, Spring Data JPA and H2 Database. The name is changed to Payroll, and then Generate Project is chosen. A zip file downloads, which unzips into a simple Maven based project containing a pom.xml build file. The guide notes that you can use Gradle, but the examples in the tutorial are Maven based, which is why the wrapper scripts mvnw and mvnw.cmd sit in the repository root.

You then have a choice. You can start a new project from scratch and work through the tutorial, or you can clone the solution repository and read the finished code. The guide suggests a third option, which is to follow the completed GitHub repository, and its own recommendation is the middle path: build the application sequentially in your own blank project, using the modules as reference. The guide also notes that a single project without multiple modules is enough to complete it, so the four module split is there for reading, not for your own build.

The guide is also explicit about where the source of truth is. The rendered tutorial at spring.io/guides/tutorials/rest/ is the publication, and the repository is the source it is generated from, so a discrepancy between the two is a matter of the page being out of date rather than of the code being wrong.

Two licence files, one for the code and one for the writing

The licence arrangement in this repository is unusual enough to be worth checking before you reuse anything from it. There is no single LICENSE file. There is LICENSE.code.txt and LICENSE.writing.txt, and the split follows the structure of the repository: the source code in the four modules is covered by one set of terms, and the prose in README.adoc, the tutorial text itself, is covered by another.

That distinction makes sense for a guide whose text is published to the web while its code is meant to be copied into your own project, and it means the two have to be read separately. A reader who copies a repository interface from the guide into a commercial codebase is relying on the code terms, not the writing terms, and the two are not the same document.

The repository metadata does not record a single licence for the project, so there is no one line to read in the GitHub sidebar. The last push was on 2026-09-01, and the repository publishes no releases, which is normal for a guide that is versioned by the Spring documentation site rather than by tags here.

Everything else in the tree supports the reading that this is a teaching artefact: the .travis.yml file, the AsciiDoc structure of README.adoc, the inclusion of source files from the modules so that the prose and the code cannot drift apart, and the front matter that tags the guide for the Spring documentation site and declares which Spring projects it uses.

Editorial conclusion

tut-rest is worth reading if you want the Spring team's own account of why a REST API is shaped the way it is, because the guide argues from HTTP's properties and shows the same payroll domain rebuilt at each step rather than presenting a finished application. It is the wrong artefact for learning a specific Spring API, since it is a narrative that mixes design argument with code, and the wrong dependency for a production service, since the code in it is teaching material. Before you start, read the guide end to end rather than skipping to the links module, decide whether Maven or Gradle suits your team because the examples are Maven-based, and read both LICENSE.code.txt and LICENSE.writing.txt, since the code and the prose are covered by separate terms.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. spring-guides/tut-rest on GitHub