📘 Premium Read: Access my best content on Medium member-only articles — deep dives into Java, Spring Boot, Microservices, backend architecture, interview preparation, career advice, and industry-standard best practices.
✅ Some premium posts are free to read — no account needed. Follow me on Medium to stay updated and support my writing.
🎓 Top 10 Udemy Courses (Huge Discount): Explore My Udemy Courses — Learn through real-time, project-based development.
▶️ Subscribe to My YouTube Channel (172K+ subscribers): Java Guides 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
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
}
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.
Comments
Post a Comment
Leave Comment