Spring Boot REST API Best Practices

🎓 Top 15 Udemy Courses (80-90% Discount): My Udemy Courses - Ramesh Fadatare — All my Udemy courses are real-time and project oriented courses.

▶️ Subscribe to My YouTube Channel (178K+ subscribers): Java Guides on YouTube

▶️ For AI, ChatGPT, Web, Tech, and Generative AI, subscribe to another channel: Ramesh Fadatare on YouTube

Building REST APIs with Spring Boot is common in the microservices ecosystem. However, simply building an API is not enough. To ensure maintainability, scalability, and efficiency, following best practices is crucial. Here we will explore some of the best practices for building REST APIs with Spring Boot and illustrate them with examples.

1. Follow RESTful Resource Naming Guidelines 

Using nouns for resource names and HTTP verbs for actions creates a clear and intuitive API structure. It helps clients understand what resources are available and what operations they can perform on them. 

Example: 

Good:

GET /users POST /users GET /users/{id} PUT /users/{id} DELETE /users/{id} 

Bad:

GET /getUsers POST /createUser GET /getUserById POST /updateUser POST /deleteUser 

In the above example, /users as a resource with HTTP GET indicates fetching user data, and with POST, it indicates creating a new user. This is more intuitive than /getUsers or /createUser, which tie the action to the URI, violating the REST principle that the URI should represent a resource, not the action on the resource.

2. Use HTTP Status Codes Appropriately 

HTTP status codes provide immediate insight into the result of an HTTP request. For instance, if a client sees 201 Created, they know their POST request successfully created a new resource. If they see 400 Bad Request, they are aware there was something wrong with their request. So basically, HTTP status codes are standardized responses to indicate the success or failure of an HTTP request. Using the correct status code is important because it provides an immediate understanding of the result of an API call.

Example: 

200 OK: The request was successful. 

201 Created: A new resource has been created. 

204 No Content: The request was successful, but there's no content to return. 

400 Bad Request: The server cannot process the request due to client-side errors. 

404 Not Found: The requested resource doesn't exist. 

500 Internal Server Error: A generic error occurred on the server.

3. Implement Exception Handling 

Use @ControllerAdvice and @ExceptionHandler to handle exceptions globally. Using @ControllerAdvice allows you to handle exceptions globally, which helps to reduce the duplication of exception-handling logic across controllers. It also aids in sending consistent error responses throughout your API.

Example:

We can create a GlobalExceptionHandler class to handle global exceptions as well as specific exceptions. In the below code snippet, we handled ResourceNotFoundException and BlogAPIException specific exceptions and we handled Exception as a global exception (it will handle all the other exceptions):

import com.springboot.blog.payload.ErrorDetails; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.ControllerAdvice; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.context.request.WebRequest; import java.util.Date; @ControllerAdvice public class GlobalExceptionHandler { // handle specific exceptions @ExceptionHandler(ResourceNotFoundException.class) public ResponseEntity<ErrorDetails> handleResourceNotFoundException(ResourceNotFoundException exception, WebRequest webRequest){ ErrorDetails errorDetails = new ErrorDetails(new Date(), exception.getMessage(), webRequest.getDescription(false)); return new ResponseEntity<>(errorDetails, HttpStatus.NOT_FOUND); } @ExceptionHandler(BlogAPIException.class) public ResponseEntity<ErrorDetails> handleBlogAPIException(BlogAPIException exception, WebRequest webRequest){ ErrorDetails errorDetails = new ErrorDetails(new Date(), exception.getMessage(), webRequest.getDescription(false)); return new ResponseEntity<>(errorDetails, HttpStatus.BAD_REQUEST); } // global exceptions @ExceptionHandler(Exception.class) public ResponseEntity<ErrorDetails> handleGlobalException(Exception exception, WebRequest webRequest){ ErrorDetails errorDetails = new ErrorDetails(new Date(), exception.getMessage(), webRequest.getDescription(false)); return new ResponseEntity<>(errorDetails, HttpStatus.INTERNAL_SERVER_ERROR); } }  

Complete example: Spring Boot Exception Handling Example

4. Validate Input Data 

Validating the incoming data helps ensure that the API behaves as expected and can help protect against malicious data. The @Valid annotation and the Java Bean Validation API allow you to define constraints directly in your model classes (e.g., @NotBlank, @Email) and automatically apply them whenever an object of that class is created or updated.

Example:

@PostMapping("/users") public ResponseEntity<User> createUser(@Valid @RequestBody User user) { User createdUser = userService.createUser(user); return new ResponseEntity<>(createdUser, HttpStatus.CREATED); } // User.java public class User { @NotBlank(message = "Name is required") private String name; @Email(message = "Email should be valid") private String email; // Other fields, getters, and setters } 

Complete example: Spring Boot DTO Validation Example

5. Use DTOs to Separate Your API Layer from Business Logic 

Data Transfer Object Design Pattern is a frequently used design pattern. It is basically used to pass data with multiple attributes in one shot from client to server, to avoid multiple calls to a remote server. 

Another advantage of using DTOs on RESTful APIs written in Java (and on Spring Boot), is that they can help to hide implementation details of domain objects (JPA entities). Exposing entities through endpoints can become a security issue if we do not carefully handle what properties can be changed through what operations.

Example:

REST API:

 // build create User REST API @PostMapping public ResponseEntity<UserDto> createUser(@RequestBody UserDto user){ UserDto savedUser = userService.createUser(user); return new ResponseEntity<>(savedUser, HttpStatus.CREATED); }

DTO class:

public class UserDto { private Long id; private String firstName; private String lastName; private String email; // create getter/setter for all the fields }

Service Layer:

 @Override public UserDto createUser(UserDto userDto) { // Convert UserDto into User JPA Entity User user = UserMapper.mapToUser(userDto); User savedUser = userRepository.save(user); // Convert User JPA entity to UserDto UserDto savedUserDto = UserMapper.mapToUserDto(savedUser); return savedUserDto; }

Mapper class:

public class UserMapper { // Convert User JPA Entity into UserDto public static UserDto mapToUserDto(User user){ UserDto userDto = new UserDto( user.getId(), user.getFirstName(), user.getLastName(), user.getEmail() ); return userDto; } // Convert UserDto into User JPA Entity public static User mapToUser(UserDto userDto){ User user = new User( userDto.getId(), userDto.getFirstName(), userDto.getLastName(), userDto.getEmail() ); return user; } }

Complete example: Spring Boot DTO Example

6. REST API Documentation

REST API documentation is critical for developers who need to understand how to use your REST APIs.Swagger (OpenAPI) is a tool that can automatically generate documentation for your API endpoints, models, and their requirements, such as expected request body structure, query parameters, and response formats. It also provides an interactive UI where developers can make API requests and see the responses, greatly easing the process of integrating with the API.

Example:

Complete tutorial: Spring Boot 3 REST API Documentation using SpringDoc OpenAPI

7. Securing REST APIs using Spring Security and JWT

Security is a major concern for any web application. Spring Security is a powerful and highly customizable authentication and access-control framework. It is essential to protect your API endpoints from unauthorized access. Configuring method-level security with roles and authorities can prevent sensitive data exposure and ensure that users can only perform actions they're permitted to.

Spring Security is used to secure web applications, REST APIs, and Microservices. Spring Security provides built-in support for both authentication and authorization. It is good practice to use JWT token-based authentication to secure the APIs. Spring Security has good support with JWT so consider using Spring Security and JWT to secure your REST APIs.

Example:

@Configuration @AllArgsConstructor public class SpringSecurityConfig { private UserDetailsService userDetailsService; @Bean public static PasswordEncoder passwordEncoder(){ return new BCryptPasswordEncoder(); } @Bean SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http.csrf().disable() .authorizeHttpRequests((authorize) -> { authorize.requestMatchers("/api/auth/**").permitAll(); authorize.anyRequest().authenticated(); }); return http.build(); } @Bean public AuthenticationManager authenticationManager(AuthenticationConfiguration configuration) throws Exception { return configuration.getAuthenticationManager(); } }

Complete example: Spring Boot + Spring Security + JWT + MySQL Database Tutorial

8. Use Pagination

Returning all records in a single request can lead to performance issues and a poor user experience. Pagination allows the API to return data in small chunks or pages, which improves performance and usability. In Spring, Pageable and Page abstractions are used to implement pagination in a repository layer.

Example:

 // get all posts rest api @GetMapping public PostResponse getAllPosts( @RequestParam(value = "pageNo", defaultValue = AppConstants.DEFAULT_PAGE_NUMBER, required = false) int pageNo, @RequestParam(value = "pageSize", defaultValue = AppConstants.DEFAULT_PAGE_SIZE, required = false) int pageSize, @RequestParam(value = "sortBy", defaultValue = AppConstants.DEFAULT_SORT_BY, required = false) String sortBy, @RequestParam(value = "sortDir", defaultValue = AppConstants.DEFAULT_SORT_DIRECTION, required = false) String sortDir ){ return postService.getAllPosts(pageNo, pageSize, sortBy, sortDir); }

Complete tutorial: Spring Boot REST API Pagination and Sorting Example

9. Implement Versioning 

Versioning your API helps to avoid breaking changes for the consumers when you introduce new features or make changes.

Example:

@RestController @RequestMapping("/api/v1/users") public class UserControllerV1 { // Controller methods } @RestController @RequestMapping("/api/v2/users") public class UserControllerV2 { // New controller methods with changes }  

10. Keep Logic Out of Controllers 

Business logic should be in services or other layers, not directly in controllers. 

Example:

@RestController @RequestMapping("/api/users") public class UserController { private final UserService userService; @PostMapping public ResponseEntity<UserDto> createUser(@Valid @RequestBody CreateUserDto createUserDto) { UserDto createdUserDto = userService.createUser(createUserDto); return new ResponseEntity<>(createdUserDto, HttpStatus.CREATED); } } 

And the UserService class:

@Service public class UserService { public UserDto createUser(CreateUserDto createUserDto) { // Convert DTO to entity, save it, and then convert back to DTO } } 

11. Perform Logging and Monitoring

Logging and monitoring your API is vital for diagnosing issues and understanding usage patterns.

Example:

@GetMapping("/{id}") public ResponseEntity<User> getUser(@PathVariable Long id) { log.info("Received request to get user with id: {}", id); User user = userService.findById(id); return ResponseEntity.ok(user); } 

By following these best practices, you will create a Spring Boot REST API that is not only functional but also robust, scalable, and easy to consume. Remember, the key to a good API is not just in how it's built but also in how it's maintained and evolved.