This project is a sample implementation of the Restbucks application described in the book REST in Practice by Jim Webber, Savas Parastatidis and Ian Robinson. It's a showcase for bringing different Spring eco-system technologies together to implement a REST web service. The application uses HAL as the primary representation format.
From the command line do:
git clone https://github.com/olivergierke/spring-restbucks.git cd spring-restbucks mvn clean package java -jar target/*.war
Note, that the curie links in the representations are currently not backed by any documents served but they will be in the future. Imagine simple HTML pages being served documenting the individual relation types.
For the usage inside an IDE do the following:
- Make sure you have an Eclipse with m2e installed (preferably STS).
- Download it from the project page.
- Run the JAR (double click or
java -jar …).
- Point it to your Eclipse installation, run the install.
- Restart Eclipse.
Import the checked out code through File > Import > Existing Maven Project…
The project uses:
- Spring Boot - 0.5.0.BUILD-SNAPSHOT
- Spring (MVC) - 4.0.0.RELEASE
- Spring Data JPA - 1.4.3.RELEASE
- Spring Data REST - 2.0.0.BUILD-SNAPSHOT
- Spring Hateoas - 0.9.0.BUILD-SNAPSHOT
- Spring Plugin - 0.8.0.RELEASE
The implementation consists of mainly two parts, the
order and the
payment part. The
Orders are exposed as REST resources using Spring Data RESTs capability to automatically expose Spring Data JPA repositories contained in the application. The
Payment process and the REST application protocol described in the book are implemented manually using a Spring MVC controller (
Here's what the individual projects used contribute to the sample in from a high-level point of view:
Spring Data JPA
The Spring Data repository mechanism is used to reduce the effort to implement persistence for the domain objects to the declaration of an interface per aggregate root. See
PaymentRepository for example. Beyond that, using the repository abstract enables the Spring Data REST module to do its work.
Spring Data REST
We're using Spring Data REST to expose the
OrderRepository as REST resource without additional effort.
Spring Hateoas provides a generic
Resource abstraction that we leverage to create hypermedia-driven representations. Spring Data REST also leverages this abstraction so that we can deploy
ResourceProcessor implementations (e.g.
PaymentorderResourceProcessor) to enrich the representations for
Order instance with links to the
PaymentController. Read more on that below in the Hypermedia section.
The final important piece is the
EntityLinks abstraction that allows to create
Link instance in a type-safe manner avoiding the repetition of URI templates and parts all over the place. See
PaymentLinks for example usage.
The Spring Plugin library provides means to collect Spring beans by type and exposing them for selection based on a selection criterion. It basically forms the foundation for the
EntityLinks mechanism provided in Spring Hateoas and our custom extension
The project uses Lombok to reduce the amount of boilerplate code to be written for Java entities and value objects.
A core focus of this sample app is to demonstrate how easy resources can be modeled in a hypermedia driven way. There are two major aspects to this challenge in Java web-frameworks:
Creating links and especially the target URL in a clean and concise way, trying to avoid the usage of Strings to define URI mappings and targets and especially the repetition of those. On the server side, we'd essentially like to express "link to the resource that manages
Orderinstances" or "link to the resource that manages a single
Cleanly separate resource functionality implementation but still allowing to leverage hypermedia to advertise new functionality for resources as the service implementation evolves. This essentially boils down to an enrichment of resource representations with links.
In our sample the core spot these challenges occur is the
payment subsystem and the
PaymentController in particular.
TODO - complete