Spring REST Example Tutorial, Spring Restful Web Services

Spring is one of the most widely used Java EE frameworks. We have earlier seen how to use Spring MVC to create Java-based web applications. Today we will learn to create Spring Restful Web Services using Spring MVC and then test it out with the Rest client. In the end, we will also look into how to invoke Spring Restful web service using Spring RestTemplate API.

Spring REST

We will use Spring latest version 4.0.0.RELEASE and utilize Spring Jackson JSON integration to send JSON response in the rest call response. The tutorial is developed in Spring STS IDE for creating Spring MVC skeleton code easily and then extended to implement Restful architecture.

Create a new Spring MVC Project in the STS, our final project will look like the below image. We will look into each of the components one by one.

Spring REST Configuration XML Files

Our pom.xml file looks like below.

STS tool generates the pom.xml file for us. However, I have updated the Spring Framework, AspectJ, SLF4J and Jackson version to the latest one as of today. Most of the part is common and generated automatically, the important point to note is that I have added Jackson JSON libraries in the dependency because we will use that to convert Objects to JSON and vice versa.

This file is generated automatically and I haven’t changed anything in that. However, if you want to change context configuration files and their location, you can do it in the web.xml file.

This file contains the shared resources that will be visible to all the web components, we will be developing a simple rest service and that’s why I haven’t changed anything here.

Most of the part is auto generated and contains boiler-plate configurations. However important points to note are annotation-driven element to support annotations based configuration and plugging in MappingJackson2HttpMessageConverter to the RequestMappingHandlerAdapter messageConverters so that Jackson API kicks in and converts JSON to Java Beans and vice versa. By having this configuration, we will be using JSON in request body and we will receive JSON data in the response.

Spring REST Model Classes

Let’s write a simple POJO class that will serve as input and output to our Restful web service methods.

The only important point to note is the use of @JsonSerialize annotation to use DateSerializer class for Date conversion from Java type to JSON format and vice versa.

Spring Restful web service End Points

We will have the following rest web services endpoints.

Sl. No URI HTTP Method Details
1 /rest/emp/dummy GET Health Check service, to insert a dummy data in the Employees data storage
2 /rest/emp/{id} GET To get the Employee object based on the id
3 /rest/emps GET To get the list of all the Employees in the data store
4 /rest/emp/create POST To create the Employee object and store it
5 /rest/emp/delete/{id} PUT To delete the Employee object from the data storage based on the id

We have a class defining all these URI as String constants.

Spring Restful web service Controller class

Our EmployeeController class will publish all the web service endpoints mentioned above. Let’s look at the code of the class and then we will learn about each of the methods in detail.

For simplicity, I am storing all the employee’s data in the HashMap empData. @RequestMapping annotation is used to map the request URI to the handler method. We can also specify the HTTP method that should be used by client application to invoke the rest method.

@ResponseBody annotation is used to map the response object in the response body. Once the response object is returned by the handler method, MappingJackson2HttpMessageConverter kicks in and convert it to JSON response.

@PathVariable annotation is the easy way to extract the data from the rest URI and map it to the method argument.

@RequestBody annotation is used to map the request body JSON data into the Employee object, again this is done by the MappingJackson2HttpMessageConverter mapping.

Rest of the code is simple and self-understood, our application is ready for deployment and testing. Just export as WAR file and copy it in the servlet container web app directory. If you have the server configured in the STS, you can simply run it on the server to get it deployed.

I am using WizTools RestClient to invoke the rest calls but you can also use Chrome extension Postman.

Below screenshots shows the different invocations of the rest APIs exposed by our application and it’s output.

Health Check – Get Dummy Employee Rest Call

Spring-Rest-Example-Project-290x450

Create Employee POST Rest Call: Make sure request Content-Type is set to “application/json” otherwise you will get HTTP Error Code 415.

Spring-Rest-Example-Project-290x450

Get Employee Rest Call
Spring-Rest-Example-GET-1

Delete Employee Rest Call
Spring-Rest-Example-PUT

Get All Employees Rest Call
Spring-Rest-Example-GET

Spring Rest Client Program

Rest Clients are good to test our rest web service but most of the times, we need to invoke rest services through our program. We can use Spring RestTemplate to invoke these methods easily. Below is a simple program invoking our application rest methods using RestTemplate API.

Most of the program is simple to understand, however when invoking rest method returning a Collection, we need to use LinkedHashMap because JSON to object conversion doesn’t know about the Employee object and converts it to the collection of LinkedHashMap. We can write a utility method to convert from LinkedHashMap to our Java Bean object.

When we run the above program, we get the following output in the console.

Another point is that RestTemplate put methods doesn’t have option to set response object because PUT method should be used to store something on the server and a simple HTTP 200 status code should be sufficient.

That’s all for the Spring Restful web application tutorial. Download the sample project from the above link and play around with it to learn more.

UPDATE: Because of so many requests to provide similar example with XML as well as supporting both XML and JSON, I have extended this application in Spring REST XML JSON Example to support both XML and JSON requests and response. I strongly suggest you go through that to see the beauty of the spring framework and how easy it is to achieve this.

By admin

Leave a Reply