spring-restbucks: the REST in Practice sample as a Spring HAL service

A book sample that is a working application

spring-restbucks is a sample implementation of the Restbucks application described in the book REST in Practice by Jim Webber, Savas Parastatidis and Ian Robinson. The README calls it a showcase for bringing different Spring ecosystem technologies together to implement a REST web service, and that framing matters. This is not a toy that fakes an API, it is the reference application from a book, built so that the code matches the concepts in the text.

The domain is a coffee shop. You order a drink, you pay for it, and you get a receipt, with orders having a status that moves from payment expected through paid to fulfilled. The state machine is small enough to understand in a minute and complete enough to exercise the interesting parts of a REST design, which is exactly why a book would choose it. The repository's main directories are server/ and android-client/, alongside a readme.md.

The server uses HAL as the primary representation format, and that choice is the technical centre of the project. A plain JSON response tells the client what the resource is; a HAL response also tells the client what it can do next, through links and embedded resources, and through HAL-FORMS templates for the transitions that are available. The consequence is that a client does not have to know the URL structure in advance, it follows the links. The Android client is described as hypermedia-aware and as adapting to changes on the server dynamically, which is the practical demonstration of why you would bother with all of this.

Building and running it with Maven

The quickstart is four commands from the command line.

git clone https://github.com/odrotbohm/spring-restbucks.git
cd spring-restbucks/server
mvn clean package
java -jar target/*.jar

The server then runs on port 8080, which is where all the exploration happens. The build is a plain Maven build, and the CI badge in the readme points at a Java CI with Maven workflow, so the build is what the project expects rather than something improvised.

For the IDE, the readme gives separate notes for Eclipse and IntelliJ, and the Eclipse route has a dependency you should know about. You need an Eclipse with m2e installed, preferably STS, and you need to install Lombok by downloading the jar from the project page, running it, pointing it at your Eclipse installation and restarting. Then you import the checked out code through File, Import, Existing Maven Project. The IntelliJ route is different: you right click server/pom.xml and select Add as Maven Project, and if you want to run the tests from the Run panel you have to edit the Maven plugin configuration, expanding byte-buddy, right clicking transform-extended and setting Execute After Build and Execute After Rebuild. The fact that the IDE notes exist at all, and that they are about a byte code transformation library, tells you this sample is on a recent enough Spring Boot that the annotation processing setup needs care.

Exploring the API through the embedded HAL Explorer

The application ships with HAL Explorer embedded, so you can browse the service at the explorer URL without installing a client. The readme walks through the flow, which is worth following because it demonstrates the hypermedia model rather than just describing it.

To get existing orders, you click the HTTP Get Request button for the restbucks:orders relation under Links, click Go, then expand any of the orders listed under Embedded Resources and click on self. To place a new order you click the HTTP Request button under the template titled Place an order under HAL-FORMS Template Elements. Both are clicks on something the server told you about, which is the whole point of the representation format.

Payment works the same way. Once an order is displayed, you use the template titled Go to checkout, which appears for all orders with status Payment expected. You enter any 16 digit number in the Credit card number field and click Go, and you will see an error because the card number is not in the database. Enter 1234123412341234 and the payment succeeds, with the readme pointing at the PaymentInitializer class as the source of the seeded demo card.

There is a caveat in the readme about the curie links in the representations. They are currently not backed by any documents served, though the project expects them to be in the future, with the idea being simple HTML pages served that document the individual relation types. So the CURIE mechanism is present in the output but the documentation pages behind it are not yet there, which is a fair example of a sample that shows a feature and one of its follow-ups at the same time.

Bash scripts for generating traffic against the running service

Two shell scripts are provided for driving the API, and both require curl and jq. The single run script is scripts/generate-traffic.sh, and by default it places a single order using the first available drink and the default location, pays with the built-in demo card, and polls until a receipt link appears.

./scripts/generate-traffic.sh
./scripts/generate-traffic.sh --scenarios scripts/order-scenarios.json
./scripts/generate-traffic.sh --scenarios scripts/order-scenarios.json --scenario java_chip_takeaway --force-error INVALID_CARD
./scripts/generate-traffic.sh --scenarios scripts/order-scenarios.json --cycle

The options are worth reading because they turn the script into a small test harness. A scenario file drives the runs, and a single scenario can be selected by name. The --cycle flag repeats indefinitely until Ctrl+C, and --random-scenario picks one at random, with a new one each iteration when combined with --cycle. The delay between runs is randomised up to a maximum, 3000 milliseconds by default, and --no-delay removes it entirely. The --force-error option has two named behaviours, INVALID_CARD for a failure case and DOUBLE_PAY which pays twice so the second payment fails.

./scripts/generate-traffic.sh --scenarios scripts/order-scenarios.json --random-scenario --cycle

The second script, scripts/run-parallel-traffic.sh, runs multiple simulated users in parallel, each executing the single run script with the random scenario and cycle options, and it prefixes the output with the user number so you can tell the streams apart. A single Ctrl+C stops all of them. The readme shows the default of five users, ten users, and a verbose variant.

./scripts/run-parallel-traffic.sh 10

This is the part of the repository that pushes beyond a book sample, because concurrent order and payment traffic with randomised timing and forced error paths is a way to see how the state machine behaves under interleaving.

The Spring stack the sample is built to demonstrate

The project description section lists the technology set, and the list is the reason the sample is worth reading. Spring Boot is the application framework and Spring MVC is the web layer, so the classic Spring stack rather than WebFlux. Spring Data JPA handles the persistence, and the use of JPA is significant because it is what lets the sample return embedded resources and collections that the hypermedia layer serialises into HAL.

The readme states the project uses Spring Boot, Spring MVC and Spring Data JPA, and the sample exists to bring these together rather than to demonstrate one of them in isolation. That framing is the difference between a reference application and a tutorial project: the point is how the parts interact, particularly how a hypermedia representation layer sits on top of an ordinary Spring MVC controller layer that returns domain objects.

The server side also includes the payment seed in PaymentInitializer, and the readme refers to the class path org.springsource.restbucks.payment, which tells you the source tree keeps the classic Restbucks package structure even though the build lives in a server/ subdirectory. The Maven module and the Android client live side by side, and the readme says the server implementation is accompanied by a hypermedia-aware Android client, so the two halves are developed together against the same API rather than the client being a separate exercise.

Where spring-restbucks is the wrong tool

Three cases argue against it. The first is production use, and the reason is simple. This is a sample, it ships a hard coded demo card number 1234123412341234 that succeeds, and any card not in the database fails with an error, which is exactly the behaviour you want in a demonstration and exactly the behaviour you cannot ship. There is also no mention in the readme of authentication, authorisation, auditing or rate limiting, and a REST administration interface for a coffee shop that lets anyone place and pay for orders is not a foundation for anything real. The second case is a team that wants a hypermedia API without a Spring dependency. The choice of HAL, the HAL-FORMS templates and the whole link following model are useful, but the sample is inseparable from the Spring implementation, and the readme lists Spring Boot, Spring MVC and Spring Data JPA as the stack. If your team is on a different framework, the code is a design reference and not a starting point. The third case is a team that wants a REST API in the ordinary sense, a set of URLs with a fixed contract that a client can code against directly. The hypermedia approach deliberately makes the client follow links, and the added indirection is a cost when the consumer is fixed and known.

On the state of the repository, the last push was on 2026-04-24 and there are no GitHub releases, so the build is the artifact rather than a tagged version, and the CI workflow is the thing that tells you whether the current tree works. The readme also names the book as the primary documentation, which is the honest framing: if you want the reasoning behind the design, the text is where it is, and the code is the illustration. The project is by Oliver Drotbohm, and it is the kind of sample that rewards reading alongside a book, with a client that demonstrates the payoff by adapting to server changes rather than hard coding paths.

Editorial conclusion

spring-restbucks suits a developer who wants one coherent example of hypermedia API design, HAL representations and Spring Boot working together, with a client that follows the server rather than hard coding paths. It does not suit a team that wants a production service, since it is a sample with a demo card number, and it does not suit a team that would rather read the book's prose than a code base. Before you run it, read the project description section of the readme for the technology list, remember the demo card number 1234123412341234 if you want payment to succeed, and note that the last push was on 2026-04-24.

Frequently asked questions

Official sources

1. Issues
2. odrotbohm/spring-restbucks on GitHub
3. README