Spring Boot RestClient Tutorial - GET, POST, PUT, and Delete Example

Author:

In this tutorial, we will learn how to use the Spring Boot 3.2 RestClient class to make GET, POST, PUT, and DELETE REST API calls. We will first create CRUD REST APIs using Spring Boot, Spring Data JPA, and MySQL database and then we will use the RestClient class to consume these CRUD REST APIs.

Introduction to RestClient Class

The RestClient class is a new addition to Spring Framework 6.1 and Spring Boot 3.2. It provides a functional style blocking HTTP API that is similar in design to WebClient. RestClient is designed to be simpler and easier to use than RestTemplate, and it offers several advantages over RestTemplate, including: 

  • A fluent API that makes it easy to chain requests together 
  • Support for annotations to configure requests 
  • Built-in error handling 
  • Support for both blocking and non-blocking requests

1. Building CRUD REST APIs using Spring Boot, Spring Data JPA, and MySQL database

Let's first create CRUD REST APIs using Spring Boot, Spring Data JPA, and MySQL database and then we will use the RestClient class to consume these CRUD REST APIs.

We are going to use a three-layer architecture in our Spring boot project:

Tools and Technologies Used:

  • Spring Boot 3.2
  • Java 17
  • Spring Data JPA
  • Hibernate
  • MySQL Database
  • Maven

1. Add Maven Dependencies

Spring Boot provides a web tool called Spring Initializer to create and bootstrap Spring boot applications quickly. Just go to https://start.spring.io/ and generate a new spring boot project.

Open the pom.xml file and add the below Maven dependencies to the project:
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-jpa</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>com.mysql</groupId>
			<artifactId>mysql-connector-j</artifactId>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<optional>true</optional>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>

2. Configure MySQL Database 

Let's first create a database, go to MySQL workbench, and use the below SQL query to create a new database: 
create database employee_management
Next, open the application.properties file and add the following properties to it.
spring.datasource.url=jdbc:mysql://localhost:3306/employee_management
spring.datasource.username=root
spring.datasource.password=Mysql@123

# Hibernate properties
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQLDialect
# create, create-drop
spring.jpa.hibernate.ddl-auto=update
Make sure that you change the spring.datasource.username & spring.datasource.password properties as per your MySQL installation.
The property spring.jpa.hibernate.ddl-auto is used for database initialization. I’ve used the value “update” for this property to create the database tables automatically. 

3. Create an Employee JPA Entity 

An Entity is a plain old Java object (POJO) that represents the data you want to store. You will need to annotate the class with @Entity and define the fields of the class along with the getters and setters for each field. Let's create an Employee class and add the following content to it:
import jakarta.persistence.*;
import lombok.*;

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Table(name = "employees")
public class Employee {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String firstName;

    @Column(nullable = false)
    private String lastName;

    @Column(nullable = false, unique = true)
    private String email;
}
Note that we are using Lombok annotations to reduce the boilerplate code (getters/setters). 

4. Create Spring Data JPA Repository - EmployeeRepository 

A repository is an interface that defines the methods for performing CRUD operations on the Entity. Spring Data JPA will automatically create the implementation for the Repository interface. Let's create an EmployeeRepository interface that extends JpaRepository:
import net.javaguides.springboot.entity.Employee;
import org.springframework.data.jpa.repository.JpaRepository;

public interface EmployeeRepository extends JpaRepository<Employee, Long> {
}

5. Create DTO Class - EmployeeDto

Let's create an EmployeeDto class to transfer the data between the client and server:
import lombok.*;

@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
@ToString
public class EmployeeDto {
    private Long id;
    private String firstName;
    private String lastName;
    private String email;
}

6. Create a Service Layer 

This layer will contain the business logic for the API and will be used to perform CRUD operations using the Repository. Let's implement the service layer, we will first create an interface and then its implementation class. 

Create EmployeeService Interface 

Let's create an EmployeeService interface and declare the following CRUD methods:
import net.javaguides.springboot.dto.EmployeeDto;

import java.util.List;

public interface EmployeeService {
    EmployeeDto createEmployee(EmployeeDto employeeDto);

    EmployeeDto getEmployeeById(Long employeeId);

    List<EmployeeDto> getAllEmployees();

    EmployeeDto updateEmployee(EmployeeDto employeeDto);

    void deleteEmployee(Long employeeId);
}

Create UserServiceImpl Class

Let's create an EmployeeServiceImpl class that implements an EmployeeService interface methods:
import lombok.AllArgsConstructor;
import net.javaguides.springboot.converter.EmployeeConverter;
import net.javaguides.springboot.dto.EmployeeDto;
import net.javaguides.springboot.entity.Employee;
import net.javaguides.springboot.service.EmployeeService;
import org.springframework.stereotype.Service;

import java.util.List;
import java.util.stream.Collectors;

@Service
@AllArgsConstructor
public class EmployeeServiceImpl implements EmployeeService {

    private EmployeeRepository employeeRepository;

    @Override
    public EmployeeDto createEmployee(EmployeeDto employeeDto) {
        Employee employee = EmployeeConverter.mapToEmployee(employeeDto);
        Employee savedEmployee = employeeRepository.save(employee);
        return EmployeeConverter.mapToEmployeeDto(savedEmployee);
    }

    @Override
    public EmployeeDto getEmployeeById(Long employeeId) {
        // we need to check whether employee with given id is exist in DB or not
        Employee existingEmployee = employeeRepository.findById(employeeId)
                .orElseThrow(() -> new IllegalArgumentException(
                        "Employee not exists with a given id : " + employeeId)
                );

        return EmployeeConverter.mapToEmployeeDto(existingEmployee);
    }

    @Override
    public List<EmployeeDto> getAllEmployees() {
        List<Employee> employees = employeeRepository.findAll();
        return employees.stream()
                .map(employee -> EmployeeConverter.mapToEmployeeDto(employee))
                .collect(Collectors.toList());
    }

    @Override
    public EmployeeDto updateEmployee(EmployeeDto employeeDto) {
        // we need to check whether employee with given id is exist in DB or not
        Employee existingEmployee = employeeRepository.findById(employeeDto.getId())
                .orElseThrow(() -> new IllegalArgumentException(
                        "Employee not exists with a given id : " + employeeDto.getId())
                );

        // convert EmployeeDto to Employee JPA entity
        Employee employee = EmployeeConverter.mapToEmployee(employeeDto);
        return EmployeeConverter.mapToEmployeeDto(employeeRepository.save(employee));
    }

    @Override
    public void deleteEmployee(Long employeeId) {

        // we need to check whether employee with given id is exist in DB or not
        Employee existingEmployee = employeeRepository.findById(employeeId)
                .orElseThrow(() -> new IllegalArgumentException(
                        "Employee not exists with a given id : " + employeeId)
                );

        employeeRepository.deleteById(employeeId);
    }
}

7. Create Controller Layer - EmployeeController 

We’ll now create the REST APIs for creating, retrieving, updating, and deleting an Employee resource. Let's create an EmployeeController class and let's build CRUD REST APIs for an Employee resource:
package net.javaguides.springboot.controller;

import lombok.AllArgsConstructor;
import net.javaguides.springboot.dto.EmployeeDto;
import net.javaguides.springboot.service.EmployeeService;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@AllArgsConstructor
@RequestMapping("api/employees")
public class EmployeeController {

    private EmployeeService employeeService;

    // build create employee REST API
    @PostMapping
    public ResponseEntity<EmployeeDto> createEmployee(@RequestBody EmployeeDto employee){
        EmployeeDto savedEmployee = employeeService.createEmployee(employee);
        return new ResponseEntity<>(savedEmployee, HttpStatus.CREATED);
    }

    // build get employee by id REST API
    // http://localhost:8080/api/employees/1
    @GetMapping("{id}")
    public ResponseEntity<EmployeeDto> getEmployeeById(@PathVariable("id") Long employeeId){
        EmployeeDto employee = employeeService.getEmployeeById(employeeId);
        //return new ResponseEntity<>(employee, HttpStatus.OK);
        return ResponseEntity.ok(employee);
    }

    // build get all employees REST API
    @GetMapping
    public ResponseEntity<List<EmployeeDto>> getAllEmployees(){
        List<EmployeeDto> employees = employeeService.getAllEmployees();
        return new ResponseEntity<>(employees, HttpStatus.OK);
    }

    // build update employee REST API
    // http://localhost:8080/api/employees/1
    @PutMapping("{id}")
    public ResponseEntity<EmployeeDto> updateEmployee(@PathVariable("id") long id
            ,@RequestBody EmployeeDto employeeDto){
        employeeDto.setId(id);
        EmployeeDto updatedEmployee = employeeService.updateEmployee(employeeDto);
        return new ResponseEntity<EmployeeDto>(updatedEmployee, HttpStatus.OK);
    }

    // build delete employee REST API
    // http://localhost:8080/api/employees/1
    @DeleteMapping("{id}")
    public ResponseEntity<String> deleteEmployee(@PathVariable("id") long id){

        // delete employee from DB
        employeeService.deleteEmployee(id);

        return new ResponseEntity<String>("Employee deleted successfully!.", HttpStatus.OK);
    }
}

8. Running Spring Boot Application 

From your IDE, run the main entry point class that contains a main() method as a standalone. The main entry point class will start the Spring Boot project in an embedded Tomcat server on port 8080.

2. Consume the CRUD REST APIs using the RestClient class

Now, we will use Spring Boot 3.2 RestClient class to consume CRUD REST APIs on an Employee resource that we built in the previous section.

1. Creating a RestClient

To create a RestClient, you can use the RestClientBuilder class. The RestClientBuilder class allows you to configure the RestClient, such as setting the base URI, adding interceptors, and configuring timeouts.
public class RestClientTest {
    private final RestClient restClient;

    public RestClientTest() {
        restClient = RestClient.builder()
                .baseUrl("http://localhost:8080")
                .build();
    }
}
Similarly to RestTemplate or any other rest client, RestClient allows us to make HTTP calls with request methods. Let’s walk through different HTTP methods to create, retrieve, modify, and delete resources.

2. Use POST to Create a Resource 

We use the POST HTTP method to submit data to a resource on a web server, often to create new records or resources in web applications. Unlike the GET method, which retrieves data, POST is designed for sending data to be processed by the server, such as when submitting a web form.

Let's use RestClient.post() method to send HTTP POST request to create an Employee resource:
    @Test
    public void createEmployee() {
        EmployeeDto newEmployee = new EmployeeDto(null, "admin", "admin", "admin123@gmail.com");

        EmployeeDto savedEmployee = restClient.post()
                .uri("/api/employees")
                .contentType(MediaType.APPLICATION_JSON)
                .body(newEmployee)
                .retrieve()
                .body(EmployeeDto.class);

        System.out.println(savedEmployee.toString());
    }

2. Use GET to Retrieve a Resource 

Let's use RestClient.get() method to make an HTTP GET request to retrieve a specific Employee:
    @Test
    public void getEmployeeById() {

        Long employeeId = 1L;

        EmployeeDto employeeDto = restClient.get()
                .uri("/api/employees/{id}", employeeId)
                .retrieve()
                .body(EmployeeDto.class);

        System.out.println(employeeDto);
    }

3. Use UPDATE to Update an Existing Resource 

Let's use RestClient.put() method to make an HTTP PUT request to update the existing Employee entity:
    @Test
    public void updateEmployee() {

        Long employeeId = 1L;

        EmployeeDto updatedEmployee = new EmployeeDto();
        updatedEmployee.setFirstName("Ramesh");
        updatedEmployee.setLastName("Fadatare");
        updatedEmployee.setEmail("ramesh@gmail.com");

        EmployeeDto result = restClient.put()
                .uri("/api/employees/{id}", employeeId)
                .contentType(MediaType.APPLICATION_JSON)
                .body(updatedEmployee)
                .retrieve()
                .body(EmployeeDto.class);

        System.out.println(result.toString());
    }

5. Use GET to Retrieve all the Resources

Let's use RestClient.get() method to make an HTTP GET request to retrieve all the Employees:
    @Test
    public void findAll() {
        List<EmployeeDto> listOfEmployees = restClient.get()
                .uri("/api/employees")
                .retrieve()
                .body(new ParameterizedTypeReference<List<EmployeeDto>>() {});

        listOfEmployees.forEach(employeeDto -> {
            System.out.println(employeeDto.toString());
        });
    }

 

6. Use DELETE to Delete an Existing Resource

Let's use RestClient.delete() method to make an HTTP DELETE request to delete a specific Employee:
    @Test
    public void deleteEmployee() {
        Long employeeId = 1L;

        String response = restClient.delete()
                .uri("/api/employees/{id}", employeeId)
                .retrieve()
                .body(String.class);

        System.out.println(response);
    }

Complete Code

Here is the complete code to use RestClient to consume CRUD REST APIs:
import net.javaguides.springboot.dto.EmployeeDto;
import org.junit.jupiter.api.MethodOrderer;
import org.junit.jupiter.api.Order;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestMethodOrder;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.MediaType;
import org.springframework.web.client.RestClient;

import java.util.List;

@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
public class RestClientTest {
    private final RestClient restClient;

    public RestClientTest() {
        restClient = RestClient.builder()
                .baseUrl("http://localhost:8080")
                .build();
    }

    @Order(1)
    @Test
    public void createEmployee() {
        EmployeeDto newEmployee = new EmployeeDto(null, "admin", "admin", "admin123@gmail.com");

        EmployeeDto savedEmployee = restClient.post()
                .uri("/api/employees")
                .contentType(MediaType.APPLICATION_JSON)
                .body(newEmployee)
                .retrieve()
                .body(EmployeeDto.class);

        System.out.println(savedEmployee.toString());
    }

    @Order(2)
    @Test
    public void getEmployeeById() {

        Long employeeId = 1L;

        EmployeeDto employeeDto = restClient.get()
                .uri("/api/employees/{id}", employeeId)
                .retrieve()
                .body(EmployeeDto.class);

        System.out.println(employeeDto);
    }

    @Order(3)
    @Test
    public void updateEmployee() {

        Long employeeId = 1L;

        EmployeeDto updatedEmployee = new EmployeeDto();
        updatedEmployee.setFirstName("Ramesh");
        updatedEmployee.setLastName("Fadatare");
        updatedEmployee.setEmail("ramesh@gmail.com");

        EmployeeDto result = restClient.put()
                .uri("/api/employees/{id}", employeeId)
                .contentType(MediaType.APPLICATION_JSON)
                .body(updatedEmployee)
                .retrieve()
                .body(EmployeeDto.class);

        System.out.println(result.toString());
    }

    @Order(4)
    @Test
    public void findAll() {
        List<EmployeeDto> listOfEmployees = restClient.get()
                .uri("/api/employees")
                .retrieve()
                .body(new ParameterizedTypeReference<List<EmployeeDto>>() {});

        listOfEmployees.forEach(employeeDto -> {
            System.out.println(employeeDto.toString());
        });
    }

    @Order(5)
    @Test
    public void deleteEmployee() {
        Long employeeId = 1L;

        String response = restClient.delete()
                .uri("/api/employees/{id}", employeeId)
                .retrieve()
                .body(String.class);

        System.out.println(response);
    }
}

Output:

7. Exception Handling

The RestClient throws two types of exceptions for a failed request: 
  1. HttpClientErrorException: with 4xx response code 
  2. HttpServerErrorException: with 5xx response code

7.1 Handling HttpClientErrorException Example

    @Test
    public void exceptionHandlingClientErrorDemo(){
        HttpClientErrorException thrown = Assertions.assertThrows(HttpClientErrorException.class,
                () -> {

                    EmployeeDto employee = restClient.get()
                            .uri("/employees/404")
                            .accept(MediaType.APPLICATION_JSON)
                            .retrieve()
                            .body(EmployeeDto.class);
                });

        Assertions.assertEquals(404, thrown.getStatusCode().value());
    }

7.2 Handling HttpServerErrorException Example

    @Test
    public void exceptionHandlingServerErrorDemo(){
        HttpServerErrorException thrown = Assertions.assertThrows(HttpServerErrorException.class,
                () -> {

                    EmployeeDto employee = restClient.get()
                            .uri("/api/employees/500")
                            .accept(MediaType.APPLICATION_JSON)
                            .retrieve()
                            .body(EmployeeDto.class);
                });

        Assertions.assertEquals(500, thrown.getStatusCode().value());
    }

GitHub Repository

The source code of this tutorial available on GitHub repository: spring-boot-3.2-restclient-demo

Conclusion 

The RestClient class is a powerful and easy-to-use tool for making HTTP requests in Spring Boot applications. It is a great alternative to RestTemplate and it is well-suited for modern Spring applications. 

I hope this tutorial has been helpful. Please let me know if you have any questions.

Related Spring and Spring Boot Tutorials/Guides:

Spring Boot Tutorials [500+] Spring Boot Testing Tutorial Spring Boot Microservice Tutorial Spring Boot Kafka Microservices Spring Boot + Apache Kafka Tutorial Spring Core Tutorial Spring MVC Tutorial Spring Data JPA Tutorial Spring Framework for Beginners Spring AOP Tutorial Spring Security Tutorial Spring Exceptions Tutorial Spring Boot Interview Questions Spring Boot Microservices Interview Questions Apache Kafka Tutorials Docker Tutorials and Guides Spring Boot RabbitMQ Tutorials Angular CRUD Example with Spring Boot Spring Boot + Angular 12 CRUD Full Stack Spring Boot + Angular 8 CRUD Full Stack Spring Boot + Angular 10 CRUD Full Stack Spring Boot + React JS CRUD Full Stack React JS ( React Hooks) + Spring Boot Spring Boot Thymeleaf CRUD Full Stack Spring Boot User Registration and Login Node Js + Express + MongoDB CRUD Vue JS + Spring Boot REST API Tutorial

Comments

Post a Comment

Leave Comment