Best Practices for Writing Spring Boot APIs

API or Application Programming Interface is a communication gateway between frontend and backend code. so robust API is crucial for smooth and reliable functionality. Spring Boot is one of the most popular frameworks for building RESTful APIs. with the help of spring boot we can build APIs with speed and simplicity. Writing APIs that are just work is good but not enough because when you are working on real world applications, APIs that are created with best practices make your development more easier. So in this article, I am sharing some real world spring boot API best practices that will help to create scalable, secure, and production ready APIs.

1. Use Meaningful & Consistent API Naming#

When it is time to define API endpoint names in your application use nouns that accurately reflect the resources your API manages (e.g., /products, /users). This makes your APIs more predictable for consumers.
Here is an example of products crud API endpoint naming convention :

GET    /api/products          // Get all products
GET    /api/products/{id}     // Get product by ID
POST   /api/products          // Create new product
PUT    /api/products/{id}     // Update product
DELETE /api/products/{id}     // Delete product

2. Follow a Consistent Project Structure#

Building APIs with well-organized project structure helps in easy collaboration as well as enhances code readability. It also promotes testing and faster debugging.
Here is an example of consistent Project Structure :

src/main/java/com/example/project
├── controller    // API endpoints
├── service       // Business logic
├── repository    // Data access layer
├── dto           // Data Transfer Objects
├── model/entity  // Database entities
├── config        // Configuration classes
├── exception     // Custom exceptions

3. Use Standardized HTTP Methods#

When you are building APIs, every API should follow proper HTTP method conventions to make your API predictable and easy to understand for other developers.
Here is an example of using proper HTTP methods :

GET	   => Retrieve data	              
POST   => Create a new resource	      
PUT	   => Update an existing resource	
PATCH	 => Partially update a resource
DELETE => Remove a resource	          

4. Use Meaningful Status Codes#

There are many new developers are return 200 OK for every response even if something went wrong. which creates confusion for any client. HTTP status codes are useful to tell the client exactly what happened with their request. So using them properly makes your APIs more predictable. 
Here are some common status codes you should use :

1. 200 OK for success
2. 201 Created for new resources
3. 400 Bad Request for invalid input
4. 404 Not Found when resource doesn’t exist
5. 500 Internal Server Error for unexpected issues

5. Use DTOs for Request and Response#

Exposing entity classes is risky and leads to tight coupling between your API and database structure. So that is why always use DTO (Data Transfer Objects) for receiving data as well as sending data to client.
For example for user entity we do not share password field in response :

public class UserResponseDto{
    private Long id;
    private String name;
    private String email;
}

6. Use Validation in DTOs#

In real world applications never trust the client because they can send incomplete, incorrect, or even malicious data that can break your application. So adding validation in DTO (Data Transfer Objects) helps to avoid incorrect or malicious data.
Here is an example of adding validation in request DTO :

@Data
public class UserRequestDTO {

    @NotBlank(message = "Name is required")
    private String name;
    
    @Email(message = "Email is not valid")
    private String email;

    @Positive(message = "Age must be greater than 0")
    private int age;
    
    @NotBlank(message = "Password is required")
    private String password;
}

7. Use Pagination For Large Dataset#

When you have thousands or even millions of records in your database and returning all records from one API will slow down your API or overload your server or even some times it will crash the client-side application. That is why Pagination is a must for APIs that deal with large datasets. Pagination helps to split the data into smaller chunks (pages). 
Here is an example of paginated API in Spring Boot :

@GetMapping("/products")
public Page<ProductResponseDTO> getAllProducts(Pageable pageable) {
    return productService.getAllProducts(pageable);
}

8. Use Exception Handling#

In our project there is a chance that something unexpected happens on the server like record not found, invalid data etc. If you do not handle these kind of exceptions properly, your API will send error messages or even stack traces to the client which is risky. That is why Exception Handling is one of the most important best practices when building Spring Boot APIs.
Spring Boot provides a clean way to handle exceptions globally using @ControllerAdvice :

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(RuntimeException.class)
		public ResponseEntity<String> handleRuntimeException(RuntimeException ex) {
		    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
													   .body(ex.getMessage());
		}
		
}

Conclusion:#

By following these best practices for writing spring boot APIs in real-world application makes your APIs clean, efficient, and secure. Also your APIs become predictable with proper endpoint naming, status codes help clients easily understand responses, and for large datasets, pagination ensures quick and efficient data retrieval, making your APIs reliable and performance-friendly.