Spring HATEOAS exists for two jobs, link creation and representation assembly

Two jobs, link creation and assembly

The README states the scope in one sentence. This project provides some APIs to ease creating REST representations that follow the HATEOAS principle when working with Spring and especially Spring MVC, and the core problem it tries to address is link creation and representation assembly.

Those are two distinct jobs, and separating them is the most useful thing the description does. Link creation is the part where a controller decides what the client may do next and expresses that as a link in the response. Representation assembly is the part where the response body, the links, and the content negotiation are put together consistently instead of being assembled by hand in every controller method.

The audience is Spring developers, and the emphasis is on Spring MVC, which is the clue to how it is meant to be used. It is not a general hypertext library and it is not a REST framework. It sits inside an existing Spring MVC application and supplies the pieces that the framework does not provide, and the phrase some APIs rather than a framework is accurate. A project that wanted a full REST client and server stack would not be looking here.

The project is Apache 2.0 licensed, the homepage is the Spring project page at spring.io/projects/spring-hateoas, and the repository is not archived, with the last push on 2026-10-13.

The commit message workaround is the most useful line in the README

There is a section called Working with Spring HATEOAS, and it is not about the library at all. It is about git.

The problem is that all commits in the repository are headlined with their GitHub issue, and git will treat a leading hash in a commit message as the start of a comment, so the issue reference is swallowed and the message appears empty in the log.

The fix is a configuration change on the clone.

git config core.commentchar "/"

Changing the comment character to a slash means git no longer treats a leading hash as a comment, and the issue numbers in the commit messages become visible again.

It is a small thing, and it is the kind of detail that only appears in a README written by people who work in the repository every day. It is also the only configuration instruction in the whole file, which tells you something about how the project expects to be used. The library is added to a Spring application through the normal dependency and import machinery, and the README's job is to point at the documentation where that is described.

The two resources it points at are the reference documentation on spring.io, under the project page's learn section, and the getting started guide for REST with HATEOAS at spring.io/guides/gs/rest-hateoas. A reader who wants to see the API in use should start with the guide rather than the README, because the README does not contain a single code example.

A release train with maintenance branches going back years

The release history in this repository is a good picture of how Spring libraries are versioned, because the Jenkins badges are still there for branches a long way back.

The README carries build status badges for main, for 1.2.x, for 1.1.x, for 1.0.x and for 0.25.x, alongside the current build and the snapshot badge and the Gitter room badge. Five maintained branches, the oldest of them a 0.25 line, all being built on continuous integration.

The current tags tell the same story from the other side. The listed releases are 3.2.0-M1, a milestone of the 3.2 line, plus 3.1.2 and 3.0.5, all published on the same day in August 2026. A milestone and two maintenance versions on one day is the release train pattern, and the repository files confirm it: release-train-settings.xml and release.properties sit at the top level, and the release instructions live in etc/release.adoc, which the README links to under Making a release.

The practical consequence for a consumer is that the version you depend on is a moving target in a specific way. A 3.0.5 patch and a 3.1.2 patch are the lines you would stay on, 3.2.0-M1 is a pre-release of the next line, and the presence of 1.x branches tells you that applications built years ago are still being patched rather than abandoned.

The build itself is Maven, with the wrapper committed as mvnw and mvnw.cmd and a .mvn/ directory, plus a settings.xml, an application.yml, a lombok.config and a src/ directory.

The badges tell you where the project sits in the Spring process

The first lines of the README are all badges, and they are worth reading as information rather than decoration. There is a GA badge pointing at the project page, a snapshot badge, a Gitter room badge, and then the Jenkins build status badges for the five maintained branches.

A GA badge next to a snapshot badge is the standard Spring arrangement for a library that publishes milestones alongside a maintained line. The snapshot badge points at the continuous integration build of the current development code, which is where the 3.2.0-M1 artefact comes from, and the GA badge is the stable reference documentation.

The Gitter badge is the community channel, and the Jenkins badge for each maintenance branch is the visible sign that those old lines are still built rather than left in place. A branch that still has a green build is a branch that still has to compile against the current toolchain, which is the part that costs a maintainer time.

Nothing about the badges describes the library's API, and that is the observation to carry into the documentation. For a project of this size and age, the README is a maintenance notice, and the actual usage information lives in the reference documentation and the getting started guide it links to.

What the README deliberately leaves out

The README for this project is short, and the omissions are consistent rather than accidental, so it is worth being explicit about what you will not find in it.

There is no dependency snippet, no import list, no controller example and no model class. There is no configuration section. There is no section on media types, on the representation model, or on the relationship between the library and the Spring Framework versions it supports. There is also no changelog excerpt, which is normal for a Spring project because the version history lives with the releases rather than in the README.

The three things the file does give you are the statement of purpose, the git workaround, and the pointers to the reference documentation and the getting started guide.

For a project with this much history and this much surface, that is a thin document, and it is a real consideration if you are evaluating it as a dependency. What you can verify from here is the scope, the licence, the maintenance pattern and the release cadence. What you cannot verify from here is how much work it takes to adopt, and the guide is where that answer lives.

One more detail in the file is worth a mention because it says something about the project. The README is in AsciiDoc, README.adoc, and the contributing and conduct files are also AsciiDoc, CODE_OF_CONDUCT.adoc, while the release documentation lives in etc/release.adoc. This is a project that keeps its documentation in the same markup system as the Spring documentation, and that keeps its build instructions in the repository rather than on a wiki.

Editorial conclusion

Spring HATEOAS fits a Spring MVC team whose API consumers are programs rather than people, and who want the client to discover the next available action instead of having it hard coded. It is the wrong choice for a service whose clients are a first party front end, where the extra representation machinery is cost without benefit. Verify first which version line your Spring Boot version expects, because the repository is publishing 3.x milestones while the maintenance branches still cover 1.x and 0.25.x, and read the getting started guide, since the README deliberately does not carry API examples.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. spring-projects/spring-hateoas on GitHub