In
this tutorial, I am writing hello world example for RESTful APIs using Spring REST features. In this example, I
will be creating two APIs which will return XML representation of resources.
Maven Dependencies
Let’s
start with runtime dependencies which you will need to write these RESTFul
APIs. In fact, all you need is Spring MVC support only.
POM.xml
Note:
If you please planning to include JSON support as
well then all you need to do is include Jackson libraries into classpath, and
same APIs will work for jackson as well.
|
Spring
MVC Configuration
For
creating APIs, you will need to configure your applications
web.xml
<! DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" < web-app > < display-name >Archetype Created Web Application</ display-name > < servlet > < servlet-name >spring</ servlet-name > < servlet-class > org.springframework.web.servlet.DispatcherServlet </ servlet-class > < load-on-startup >1</ load-on-startup > </ servlet > < servlet-mapping > < servlet-name >spring</ servlet-name > < url-pattern >/</ url-pattern > </ servlet-mapping > </ web-app > |
spring-servlet.xml
xml version="1.0"
encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:mvc="http://www.springframework.org/schema/mvc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-4.1.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-4.1.xsd
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc-4.1.xsd">
<context:component-scan base-package="com.accenture"
/>
<mvc:annotation-driven />
</beans>
JAXB
Annotated Model Objects
You
will need to annotate your model objects with jaxb annotations so that JAXB can marshal the java object into XML representation
to be sent to client for that API.
EmployeeVO.java
import
java.io.Serializable;
import
javax.xml.bind.annotation.XmlAccessType;
import
javax.xml.bind.annotation.XmlAccessorType;
import
javax.xml.bind.annotation.XmlAttribute;
import
javax.xml.bind.annotation.XmlElement;
import
javax.xml.bind.annotation.XmlRootElement;
@XmlRootElement
(name = "employee")
@XmlAccessorType(XmlAccessType.NONE)
public
class EmployeeVO implements Serializable
{
private static final long serialVersionUID
= 1L;
@XmlAttribute
private Integer id;
@XmlElement
private String firstName;
@XmlElement
private String lastName;
@XmlElement
private String email;
public EmployeeVO(Integer id, String
firstName, String lastName, String email) {
super();
this.id = id;
this.firstName = firstName;
this.lastName = lastName;
this.email = email;
}
public EmployeeVO(){
}
//Setters and Getters
@Override
public String toString() {
return "EmployeeVO [id=" + id
+ ", firstName=" + firstName
+ ", lastName=" +
lastName + ", email=" + email + "]";
}
}
EmployeeListVO.java
import
java.util.ArrayList;
import
java.util.List;
import
javax.xml.bind.annotation.XmlRootElement;
@XmlRootElement
(name="employees")
public
class EmployeeListVO implements Serializable
{
private static final long serialVersionUID
= 1L;
private List employees =
new ArrayList();
public List
getEmployees() {
return employees;
}
public void setEmployees(List
employees) {
this.employees = employees;
}
}
REST
Controller
This
is main class which will decide that which API will behave which way.
EmployeeRESTController.java
import
org.springframework.http.HttpStatus;
import
org.springframework.http.ResponseEntity;
import
org.springframework.web.bind.annotation.PathVariable;
import
org.springframework.web.bind.annotation.RequestMapping;
import
org.springframework.web.bind.annotation.ResponseBody;
import
org.springframework.web.bind.annotation.RestController;
import
com.howtodoinjava.demo.model.EmployeeListVO;
import
com.howtodoinjava.demo.model.EmployeeVO;
@RestController
public
class EmployeeRESTController
{
@RequestMapping(value =
"/employees")
public EmployeeListVO getAllEmployees()
{
EmployeeListVO employees = new
EmployeeListVO();
EmployeeVO empOne = new
EmployeeVO(1,"Naresh","C","nareshc@gmail.com");
EmployeeVO empTwo = new
EmployeeVO(2,"Anil","B","anilb@yahoo.com");
EmployeeVO empThree = new
EmployeeVO(3,"krish","J","krishj@gmail.com");
employees.getEmployees().add(empOne);
employees.getEmployees().add(empTwo);
employees.getEmployees().add(empThree);
return employees;
}
@RequestMapping(value =
"/employees/{id}")
public ResponseEntity
getEmployeeById (@PathVariable("id") int id)
{
if (id <= 3) {
EmployeeVO employee = new
EmployeeVO(1,"Naresh","C","nareshc@gmail.com");
return new
ResponseEntity(employee, HttpStatus.OK);
}
return new
ResponseEntity(HttpStatus.NOT_FOUND);
}
}
Let’s
note down few important things.
1) We
have used @RestController annotation.
Till Spring 3, we would have been using @Controller annotation and in
that case it was important to use@ResponseBody annotation as
well. e.g.
@Controller
public
class EmployeeRESTController
{
@RequestMapping(value
= "/employees")
public
@ResponseBody EmployeeListVO getAllEmployees()
{
//API
code
}
}
|
Spring
4 introduced @RestController which is combination of @Controller
+ @ResponseBody. So when using @RestController, you do not need to use@ResponseBody.
It’s optional.
2) Here
we are relying on the Spring MVC HttpMessageConverters to convert an
object to the xml representation requested by the user. @ResponseBody annotation
(included through @RestController) tells Spring MVC that the result of the
method should be used as the body of the response. As we want XML this
marshaling is done by the Jaxb2RootElementHttpMessageConverter provided
by Spring which is automatically registered in spring context if JAXB libraries
are found in classpath. As I am using JRE 7 to run this application and it has
JAXB inbuilt, so I do not need to add external dependency through maven.
3) Due
to the @ResponseBody annotation, we don’t need the view name anymore
but can simply return the employees object.
4) Instead
of returning the java objects directly, you can wrap them insideResponseEntity.
The ResponseEntity is a class in Spring MVC that acts as a wrapper
for an object to be used as the body of the result together with a HTTP status
code. This provides greater control over what you are returning to client in
various use cases. e.g. returning a 404 error if no employee is found for given
employee id.
Test
the APIs
Let’s
test above REST APIs.
1)
Hit URL : http://localhost:8080/springrestexample/employees
You
can pass accept header “application/xml” as well.
No comments:
Post a Comment