monkey codes
monkey codes

Random bits of knowledge and laughable mistakes from a real world code monkey.

Curious software developer, motorcycle enthusiast, rugby fanatic and biltong connoisseur. My code always works sometimes.




monkey codes

Boot Your RESTful API Using Spring

Johan ZietsmanJohan Zietsman

How to build a HATEOAS RESTful API using Spring Boot and Mongo.

With microservices being a popular approach on greenfield projects and equally used the liven up aging architectures, I wanted to explore what the Groovy / Spring world had to offer in this regard. Spring Boot is arguably the simplest way to get a lightweight RESTful service off the ground. In this post I will cover the basics on getting a HATEOAS RESTful service that stores Person entities in a Mongo database.

The code can be found on github.

What is HAL & HATEOAS?

HATEOAS (Hypermedia as the Engine of Application State) is a style of REST application architecture that allows a client to dynamically navigate the related resources through hypermedia links in the body of a response. HAL (Hypertext Application Language) defines a simple format to hyperlink between resources in your API, thus HAL can be used to implement HATEOAS.


Having stared at Maven xml files for many years I felt inclined to see how the other side lives and decided to take Gradle for a test drive. It did not take a lot of effort to get the build going but you do need to have a few obvious components installed before you can start.


Make sure java is installed and on your path. I like to install it in /opt with a symlink current pointing to the version. Then stick current into your profile, this allows you to easily switch between versions by just changing the current symlink.

mkdir /opt/java && cd /opt/java

curl -v -j -k -L -H "Cookie: oraclelicense=accept-securebackup-cookie" > jdk-8u25-linux-x64.tar.gz

tar -xvf jdk-8u25-linux-x64.tar.gz  
ln -sf /opt/java/jdk1.8.0_71 /opt/java/current  
echo 'export JAVA_HOME=/opt/java/current' >> ~/.profile  
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.profile  
source ~/.profile  


Nope, its not a superhero, but can easily pass for one. You can think of it as RVM for Java or Groovy.

curl -s | bash  
source "/home/vagrant/.sdkman/bin/"  
sdk install springboot  

Now you should have the spring command available in your terminal.


Mongo is a popular document store that will be used to persist the Person entities.

mkdir /opt/mongo  
cd /opt/mongo  
wget wget  
tar -xvf mongodb-linux-x86_64-ubuntu1404-3.2.1.tgz  
ln -sf mongodb-linux-x86_64-ubuntu1404-3.2.1 current  
mkdir /opt/mongo/data  
/opt/mongo/current/bin/mongod --dbpath /opt/mongo/data/

Bootstrapping the project

I always find it easier to tinker with something that is working when you are learning a new technology. Spring initializr provides a browser based wizard to generate a project skeleton. Make sure you select Gradle project with the following starters:

Extract the generated zip archive in your project folder. The project's root folder will contain a set of Gradle wrapper scripts and jar file that provides a convenient way of bootstrapping your gradle build environment. It can be committed with the rest of the project files and will download and cache the version of Gradle used for the project.

To build the project run:


This might take a while the first time since it needs to download Gradle and all the projects dependencies but stay calm and don't panic, the second time will be much faster since all the dependencies are cached locally.

Hotswapping with Spring-Loaded

This might speed up your development cycle to a certain extent. It will reload classes that have changed without restarting the app. Unfortunately intellij does not recompile automatically, when a source file changes you have to force it to compile (SHIFT + COMMAND + F9 on Mac). Eclipse users don't have this problem.

Download spring-loaded then start the main app with javaagent:

-javaagent:$PATH_TO_JAR/springloaded-1.2.5.RELEASE.jar -noverify

The Code

This example comes straight from Spring.

The first step is to create an Entity that you would like to expose as a RESTful service.

package codes.monkey.people


class Person {  
    String id

    String firstName, lastName

and now for the best part, create Repository Interface and Spring will take care of the rest! No implementation required.

package codes.monkey.people  

@RepositoryRestResource(collectionResourceRel = 'people', path = 'people')
interface PersonRepository extends MongoRepository<Person, String>{

    List<Person> findByLastName(@Param('name') String name)

and that is it folks. You now have a HATEOAS RESTful API.

The server can be started through gradlew

 ./gradlew bootRun

To test it you can issue a curl command to create a Person.

curl -i -X POST -H "Content-Type:application/json" -d '{  "firstName" : "Bilbo",  "lastName" : "Baggins" }' http://localhost:8080/people  

The RESTful resources can be naturally discovered in a true HATEOAS fashion:

curl http://localhost:8080  

results in

  "_links" : {
    "people" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    "profile" : {
      "href" : "http://localhost:8080/profile"

Custom search queries like findByLastName will be available under /people/search/findByLastName{?name}.


Spring Boot supports configuration changes through properties or yaml files which can be activated through Spring Profiles. For example, to change the host that MongoDB run's on, you can edit or application-$ and add the following entry:  

The Spring Boot documentation contains a list of supported configuration keys.


The Gradle build contains a task to build a single executable jar that contains all of the required dependencies to run the app.

./gradlew build
java -jar build/libs/spring-boot-restful-0.0.1-SNAPSHOT.jar  


Most of this post was taken up by getting the environment configured, that aside, with Spring Boot you really do get a lot in return for your code. As this example shows, a full blown HATEOAS RESTful API with MongoDB backed storage for only a few lines of code by Java standards.


Accessing MongoDB Data with REST

Curious software developer, motorcycle enthusiast, rugby fanatic and biltong connoisseur. My code always works sometimes.