Spring Boot is an open source Java -based framework, used to build stand-alone and production ready spring applications.
In this article, we will show you how to build simple REST API from scratch using Spring Boot 2.2.9, Spring Data JPA/Hibernate with MySQL as database.
Requirement
We need to create a simple REST API to create, update, delete and get Users and its corresponding purchased Orders.
Maven dependencies
<dependencies>
<!--Web-Basic dependencies-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--Spring Data JPA-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<!--MYSQL -->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
</dependency>
<!--Model mapper -->
<dependency>
<groupId>org.modelmapper</groupId>
<artifactId>modelmapper</artifactId>
<version>2.3.2</version>
</dependency>
<!--Spring Boot test-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
</exclusion>
</exclusions>
</dependency>
<!--Junit 5-->
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-engine</artifactId>
<scope>test</scope>
</dependency>
<!-- In Memory database useful for unit testing-->
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
Three Layers of Rest Service
Controller Layer
It is top most layer and it receives request from client and invokes service layer. The result from service layer is processed and response is sent back to client.
Service Layer
It is middle layer and is called by Controller layer. It does business operation and calls lowermost data layer.
Data / Persistence / Repository Layer
This layer does all interaction with underlying database.
Create Data / Persistence / Repository Layer
Implementing persistence /data layer in Spring is very simple and is two step process.
1. Create Entity Class for User and Order
@Entity(name = "users")
public class User implements Serializable {
private static final long serialVersionUID = -465L;
@Id
@GeneratedValue
private Long id;
@Column(nullable = false, length = 50)
private String firstName;
@Column(nullable = false, length = 50)
private String lastName;
@Column(nullable = false, length = 120)
private String email;
@Column(nullable = false, length = 50)
private String firstLineOfAddress;
@Column(length = 50)
private String secondLineOfAddress;
@Column(nullable = false, length = 50)
private String town;
@Column(nullable = false, length = 10)
private String postCode;
// Getters and Setters(Omitted for brevity)
}
@Entity(name = "orders")
public class Order implements Serializable {
private static final long serialVersionUID = -466L;
@Id
@GeneratedValue
private Long id;
@Column(nullable = false, length = 120)
private String description;
@Column(nullable = false, length = 120)
private long priceInPence;
@Column(nullable = false)
private boolean completedStatus = false;
@ManyToOne(fetch = FetchType.LAZY, optional = false)
@JoinColumn(name = "user_id", nullable = false)
@OnDelete(action = OnDeleteAction.CASCADE)
@JsonIgnore
private User user;
// Getters and Setters(Omitted for brevity)
}
Above annotations are basically JPA annotations.
@Entity(name = “users”) tells that data contained in class will be stored in database table “users”
@Column(nullable = false, length = 50) Indicates column name used in database table. Length indicates permitted column length in table.
Nullable indicates if the column in table can be null or not. Because every user may not have second line of address, we made this field nullable
Domain objects are sometimes stored in http-session for caching/optimisation purpose, hence making the object Serializable is a good practice.
serialVersionUID is usually very big long number.
@ManyToOne(fetch = FetchType.LAZY, optional = false) indicates User to Order is many to one mapping, which means a user can have zero
or many orders. But one order can belong to one user only.
@JoinColumn(name = “user_id”, nullable = false) indicates Order table will have user_id column which will reference id of users table
@OnDelete(action = OnDeleteAction.CASCADE) indicates that parent user row is deleted in users table, corresponding order row will also
be deleted in the orders table
@JsonIgnore is used to hide the field, when order is serialised into json response body , which is sent to client. We don’t want user details in
order response body
2. Create Repository Interface for User and Order
@Repository
public interface UserRepository extends CrudRepository<User, Long> {
Optional<User> findByEmail(String email);
}
@Repository
public interface OrderRepository extends CrudRepository<Order, Long> {
Optional<Order> findByIdAndUserId(Long id, Long userId);
List<Order> findAllByUser(User user);
}
Spring will automatically implement above interface.
@Repository is Spring annotation to indicate that it is data layer.
findByEmail finds User by its email field.
findByIdAndUserId returns order by OrderId and UserId
findAllByUser returns order by user
Create Service Layer
It s good practice to implement service layer by “programming to interface” principle.
Service Interface
public interface UserService {
User createUser(User user);
User updateUser(Long id, User user);
User patchUpdateUser(Long id, User user);
User getUserById(Long id);
List<User> getUsers();
void deleteUser(Long id);
}
public interface OrderService {
Order createOrder(Long userId, Order order);
Order updateOrder(Long userId, Long orderId, Order order);
Order patchUpdateOrder(Long userId, Long orderId, Order order);
Order getOrder(Long userId, Long orderId);
List<Order> getAllOrdersByUserId(Long userId);
void deleteOrder(Long userId, Long orderId);
}
Service Implementation
@Service
public class UserServiceImpl implements UserService {
@Autowired
private UserRepository userRepository;
@Override
public User getUserById(Long id) {
Optional<User> maybeUser = userRepository.findById(id);
return maybeUser.orElseThrow(() -> new RuntimeException("User not found"));
}
@Override
public User createUser(User user) {
userRepository.findByEmail(user.getEmail())
.ifPresent(p -> {
throw new RuntimeException("User with email " + p.getEmail() + " already exists ");
});
return userRepository.save(user);
}
@Override
public User updateUser(Long id, User user) {
User userFound = userRepository.findById(id).orElseThrow(() -> new RuntimeException("User not found"));
userFound.setFirstName(user.getFirstName());
userFound.setLastName(user.getLastName());
userFound.setEmail(user.getEmail());
userFound.setFirstLineOfAddress(user.getFirstLineOfAddress());
userFound.setSecondLineOfAddress(user.getSecondLineOfAddress());
userFound.setTown(user.getTown());
userFound.setPostCode(user.getPostCode());
return userRepository.save(userFound);
}
@Override
public User patchUpdateUser(Long id, User user) {
User userFound = userRepository.findById(id).orElseThrow(() -> new RuntimeException("User not found"));
ModelMapper modelMapper = new ModelMapper();
//copy only non null values
modelMapper.getConfiguration().setSkipNullEnabled(true).setMatchingStrategy(MatchingStrategies.STRICT);
modelMapper.map(user, userFound);
return userRepository.save(userFound);
}
@Override
public void deleteUser(Long id) {
User userFound = userRepository.findById(id).orElseThrow(() -> new RuntimeException("User not found"));
userRepository.delete(userFound);
}
@Override
public List<User> getUsers() {
Iterable<User> userIterable = userRepository.findAll();
return StreamSupport.stream(userIterable.spliterator(), false)
.collect(Collectors.toList());
}
}
@Service
public class OrderServiceImpl implements OrderService {
@Autowired
private OrderRepository orderRepository;
@Autowired
private UserRepository userRepository;
@Override
public Order createOrder(Long userId, Order order) {
User user = userRepository.findById(userId)
.orElseThrow(() -> new RuntimeException("User with id " + userId + " Not found"));
order.setUser(user);
return orderRepository.save(order);
}
@Override
public Order getOrder(Long userId, Long orderId) {
return orderRepository.findByIdAndUserId(orderId, userId)
.orElseThrow(() -> new RuntimeException("User with id " + userId + " and order id " + orderId + " Not found"));
}
@Override
public List<Order> getAllOrdersByUserId(Long userId) {
User user = userRepository.findById(userId)
.orElseThrow(() -> new RuntimeException("User with id " + userId + " Not found"));
return orderRepository.findAllByUser(user);
}
@Override
public Order updateOrder(Long userId, Long orderId, Order order) {
Order orderFound = orderRepository.findByIdAndUserId(orderId, userId)
.orElseThrow(() -> new RuntimeException("User with id " + userId + " and order id " + orderId + " Not found"));
orderFound.setDescription(order.getDescription());
orderFound.setPriceInPence(order.getPriceInPence());
return orderRepository.save(orderFound);
}
@Override
public Order patchUpdateOrder(Long userId, Long orderId, Order order) {
Order orderFound = orderRepository.findByIdAndUserId(orderId, userId)
.orElseThrow(() -> new RuntimeException("User with id " + userId + " and order id " + orderId + " Not found"));
if (order.getDescription() != null)
orderFound.setDescription(order.getDescription());
if (order.getPriceInPence() != 0)
orderFound.setPriceInPence(order.getPriceInPence());
return orderRepository.save(orderFound);
}
@Override
public void deleteOrder(Long userId, Long orderId) {
Order order = orderRepository.findByIdAndUserId(orderId, userId)
.orElseThrow(() -> new RuntimeException("User with id " + userId + " and order id " + orderId + " Not found"));
orderRepository.delete(order);
}
}
Create Controller Layer
User Controller
@RestController
@RequestMapping("/api/users")
public class UserController {
@Autowired
private UserService userService;
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
return userService.getUserById(id);
}
@GetMapping()
public List<User> getAllUsers() {
return userService.getUsers();
}
@PostMapping
public ResponseEntity<User> createUser(@RequestBody User user) {
User createdUser = userService.createUser(user);
return ResponseEntity.status(HttpStatus.CREATED).body(createdUser);
}
@PutMapping("/{id}")
public User updateUser(@PathVariable Long id, @RequestBody User user) {
return userService.updateUser(id, user);
}
@PatchMapping("/{id}")
public User patchUpdateUser(@PathVariable Long id, @RequestBody User user) {
return userService.patchUpdateUser(id, user);
}
@DeleteMapping("/{id}")
public ResponseEntity<?> deleteUser(@PathVariable Long id) {
userService.deleteUser(id);
return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
}
}
Order Controller
@RestController
@RequestMapping("/api/users")
public class OrderController {
@Autowired
private OrderService orderService;
@PostMapping("/{userId}/orders")
public ResponseEntity<Order> createOrder(@PathVariable Long userId, @RequestBody Order order) {
Order createdOrder = orderService.createOrder(userId, order);
return ResponseEntity.status(HttpStatus.CREATED).body(createdOrder);
}
@GetMapping("/{userId}/orders/{orderId}")
public Order getOrder(@PathVariable Long userId, @PathVariable Long orderId) {
return orderService.getOrder(userId, orderId);
}
@PutMapping("/{userId}/orders/{orderId}")
public Order updateOrder(@PathVariable Long userId, @PathVariable Long orderId, @RequestBody Order order) {
return orderService.updateOrder(userId, orderId, order);
}
@PatchMapping("/{userId}/orders/{orderId}")
public Order patchUpdateOrder(@PathVariable Long userId, @PathVariable Long orderId, @RequestBody Order order) {
return orderService.patchUpdateOrder(userId, orderId, order);
}
@GetMapping("/{userId}/orders")
public List<Order> getAllOrders(@PathVariable Long userId) {
return orderService.getAllOrdersByUserId(userId);
}
@DeleteMapping("/{userId}/orders/{orderId}")
public ResponseEntity<?> deleteOrder(@PathVariable Long userId, @PathVariable Long orderId) {
orderService.deleteOrder(userId, orderId);
return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
}
}
Build and Run application
mvn spring-boot:run
Test API manually
We can test REST API manually with Postman . Following shows sample request and responses for various operations
Post User
http://localhost:8080/api/users
Request Body
{
"firstName":"Steve",
"lastName":"Rob",
"email":"steverob@test.com",
"firstLineOfAddress":"111 Pinewood Grove",
"secondLineOfAddress":"Commercial street",
"town":"London",
"postCode":"W7 8AG"
}
Response
{
"id": 44,
"firstName":"Steve",
"lastName":"Rob",
"email":"steverob@test.com",
"firstLineOfAddress":"111 Pinewood Grove",
"secondLineOfAddress":"Commercial street",
"town":"London",
"postCode":"W7 8AG"
}
Get User
http://localhost:8080/api/users/44
Response
{
"id": 44,
"firstName":"Steve",
"lastName":"Rob",
"email":"steverob@test.com",
"firstLineOfAddress":"111 Pinewood Grove",
"secondLineOfAddress":"Commercial street",
"town":"London",
"postCode":"W7 8AG"
}
Put User
http://localhost:8080/api/users/44
Request Body
{
"firstName":"Steveupdated",
"lastName":"Robupdated",
"email":"steverob@test.com",
"firstLineOfAddress":"111 Pinewood Grove",
"secondLineOfAddress":"Commercial street",
"town":"London",
"postCode":"W7 8AG"
}
Response
{
"id": 44,
"firstName":"Steveupdated",
"lastName":"Robupdated",
"email":"steverob@test.com",
"firstLineOfAddress":"111 Pinewood Grove",
"secondLineOfAddress":"Commercial street",
"town":"London",
"postCode":"W7 8AG"
}
Patch User
http://localhost:8080/api/users/44
Request Body
{
"firstName":"SteveupdatedAgain",
"lastName":"RobupdatedAgain"
}
Response
{
"id": 44,
"firstName":"SteveupdatedAgain",
"lastName":"RobupdatedAgain",
"email":"steverob@test.com",
"firstLineOfAddress":"111 Pinewood Grove",
"secondLineOfAddress":"Commercial street",
"town":"London",
"postCode":"W7 8AG"
}
Post Order
http://localhost:8080/api/api/users/44/orders
Request Body
{
"description":"Awesome phone",
"priceInPence":1200,
"completedStatus": false
}
Response
{
"id": 45,
"description":"Awesome phone",
"priceInPence":1200,
"completedStatus": false
}
Get Order
http://localhost:8080/api/users/44/orders/45
Response
{
"id": 45,
"description":"Awesome phone",
"priceInPence":1200,
"completedStatus": false
}
Complete Source Code Location
https://github.com/ranjesh1/spring-boot2-rest-order-services.git
Unit Tests
Creating unit tests are described in another post ‘Unit Testing with Spring Boot Application‘
