This guide walks you through the process of creating a "hello world" Hypermedia Driven REST web service with Spring.
Hypermedia is an important aspect of REST. It allows you to build services that decouple client and server to a large extent and allow them to evolve independently. The representations returned for REST resources contain not only data, but links to related resources. Thus the design of the representations is crucial to the design of the overall service.
You’ll build a hypermedia-driven REST service with Spring HATEOAS, a library of APIs that you can use to easily create links pointing to Spring MVC controllers, build up resource representations, and control how they’re rendered into supported hypermedia formats such as HAL.
The service will accept HTTP GET requests at:
http://localhost:8080/greeting
and respond with a JSON representation of a greeting enriched with the simplest possible hypermedia element, a link pointing to the resource itself:
{
"content":"Hello, World!",
"_links":{
"self":{
"href":"http://localhost:8080/greeting?name=World"
}
}
}The response already indicates you can customize the greeting with an optional name parameter in the query string:
http://localhost:8080/greeting?name=User
The name parameter value overrides the default value of "World" and is reflected in the response:
{
"content":"Hello, User!",
"_links":{
"self":{
"href":"http://localhost:8080/greeting?name=User"
}
}
}Now that you’ve set up the project and build system, you can create your web service.
Begin the process by thinking about service interactions.
The service will expose a resource at /greeting to handle GET requests, optionally with a name parameter in the query string. The GET request should return a 200 OK response with JSON in the body that represents a greeting.
Beyond that, the JSON representation of the resource will be enriched with a list of hypermedia elements in a _links property. The most rudimentary form of this is a link pointing to the resource itself. So the representation should look something like this:
{
"content":"Hello, World!",
"_links":{
"self":{
"href":"http://localhost:8080/greeting?name=World"
}
}
}The content is the textual representation of the greeting. The _links element contains a list of links, in this case exactly one with the relation type of rel and the href attribute pointing to the resource just accessed.
To model the greeting representation, you create a resource representation class. As the _links property is a fundamental property of the representation model, Spring HATEOAS ships with a base class ResourceSupport that allows you to add instances of Link and ensures that they are rendered as shown above.
So you simply create a plain old java object extending ResourceSupport and add the field and accessor for the content as well as a constructor:
src/main/java/hello/Greeting.java
link:complete/src/main/java/hello/Greeting.java[role=include]-
@JsonCreator - signal on how Jackson can create an instance of this POJO
-
@JsonProperty - clearly marks what field Jackson should put this constructor argument into
|
Note
|
As you’ll see in steps below, Spring will use the Jackson JSON library to automatically marshal instances of type Greeting into JSON.
|
Next you create the resource controller that will serve these greetings.
In Spring’s approach to building RESTful web services, HTTP requests are handled by a controller. The components are easily identified by the @RestController annotation, which combines the @Controller and @ResponseBody annotations. The GreetingController below handles GET requests for /greeting by returning a new instance of the Greeting class:
src/main/java/hello/GreetingController.java
link:complete/src/main/java/hello/GreetingController.java[role=include]This controller is concise and simple, but there’s plenty going on. Let’s break it down step by step.
The @RequestMapping annotation ensures that HTTP requests to /greeting are mapped to the greeting() method.
|
Note
|
The above example does not specify GET vs. PUT, POST, and so forth, because @RequestMapping maps all HTTP operations by default. Use @RequestMapping(path="/greeting", method=RequestMethod.GET) to narrow this mapping. In that case you also want to import org.springframework.web.bind.annotation.RequestMethod;.
|
@RequestParam binds the value of the query string parameter name into the name parameter of the greeting() method. This query string parameter is not required; if it is absent in the request, the defaultValue of "World" is used.
Because the @RestController annotation is present on the class, an implicit @ResponseBody annotation is being added onto the greeting method. This causes Spring MVC to render the returned HttpEntity and its payload, the Greeting, directly to the response.
The most interesting part of the method implementation is how you create the link pointing to the controller method and how you add it to the representation model. Both linkTo(…) and methodOn(…) are static methods on ControllerLinkBuilder that allow you to fake a method invocation on the controller. The LinkBuilder returned will have inspected the controller method’s mapping annotation to build up exactly the URI the method is mapped to.
|
Note
|
Spring HATEOAS respects various X-FORWARDED- headers. If you put a Spring HATEOAS service behind a proxy and properly configure it with X-FORWARDED-HOST headers, the resulting links will be properly formatted. |
The call to withSelfRel() creates a Link instance that you add to the Greeting representation model.
Although it is possible to package this service as a traditional web application archive or WAR file for deployment to an external application server, the simpler approach demonstrated below creates a standalone application. You package everything in a single, executable JAR file, driven by a good old Java main() method. And along the way, you use Spring’s support for embedding the Tomcat servlet container as the HTTP runtime, instead of deploying to an external instance.
src/main/java/hello/Application.java
link:complete/src/main/java/hello/Application.java[role=include]https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/build_an_executable_jar_subhead.adoc https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/build_an_executable_jar_with_both.adoc
Logging output is displayed. The service should be up and running within a few seconds.
Now that the service is up, visit http://localhost:8080/greeting, where you see:
{
"content":"Hello, World!",
"_links":{
"self":{
"href":"http://localhost:8080/greeting?name=World"
}
}
}Provide a name query string parameter with http://localhost:8080/greeting?name=User. Notice how the value of the content attribute changes from "Hello, World!" to "Hello, User!" and the href attribute of the self link reflects that change as well:
{
"content":"Hello, User!",
"_links":{
"self":{
"href":"http://localhost:8080/greeting?name=User"
}
}
}This change demonstrates that the @RequestParam arrangement in GreetingController is working as expected. The name parameter has been given a default value of "World", but can always be explicitly overridden through the query string.
Congratulations! You’ve just developed a hypermedia-driven RESTful web service with Spring HATEOAS.
The following guides may also be helpful: