How to Build a REST API using Java Spring Boot

REST (Representational State Transfer) is an architectural style that uses HTTP methods to create, read, update, and delete (CRUD) resources. RESTful APIs are stateless and allow clients to interact with resources using standard HTTP verbs such as GET, POST, PUT, and DELETE.

Spring Boot is a framework that simplifies the creation of stand-alone, production-grade Spring-based applications. It provides a range of non-functional features common in large-scale projects (e.g., embedded servers, security, and monitoring) with minimal boilerplate code.

Spring Boot's simplicity and power make it an excellent choice for building REST APIs. By leveraging Spring Boot, you can create RESTful services quickly and efficiently, allowing you to focus on the business logic rather than configuration and infrastructure.

Connect with high-paying remote Java projects through Index.dev's remote work platform. Sign up today!

1. Setting Up the Development Environment

Before we begin, you'll need to set up your development environment. Here's what you'll need:

• Java Development Kit (JDK) 17 or higher: Download and install the JDK from the Oracle website or use OpenJDK.
• IDE: IntelliJ IDEA, Eclipse, or any other Java IDE. IntelliJ IDEA is recommended for its seamless Spring Boot integration.
• Maven or Gradle: A build automation tool that manages project dependencies. Maven is more commonly used with Spring Boot.

Make sure to set up the environment variables for the JDK and Maven/Gradle correctly.

2. Creating a Spring Boot Project

You can create a Spring Boot project using Spring Initializr, which is a web-based tool that allows you to generate a Spring Boot project with all the necessary dependencies.

Step 1: Generate a Spring Boot Project

1. Go to Spring Initializr.

2. Choose the following settings:

• Project: Maven Project
• Language: Java
• Spring Boot: 3.0.0 (or the latest version)
• Project Metadata:
• Group: com.example
• Artifact: restapi
• Name: restapi
• Package name: com.example.restapi
• Packaging: Jar
• Java Version: 17

3. Add Dependencies:

• Spring Web: For building web, including RESTful, applications using Spring MVC.
• Spring Data JPA: For interacting with databases using JPA (Java Persistence API).
• H2 Database: An in-memory database for development and testing.

4. Click Generate to download the project as a .zip file.

Step 2: Import the Project into Your IDE

1. Extract the downloaded .zip file.
2. Open your IDE and import the project as a Maven project.
3. The IDE will download the necessary dependencies and set up the project structure.

3. Understanding the Spring Boot Structure

A typical Spring Boot project has the following structure:

src

├── main

│   ├── java

│   │   └── com.example.restapi

│   │       ├── RestApiApplication.java

│   │       ├── controller

│   │       ├── model

│   │       ├── repository

│   │       └── service

│   └── resources

│       ├── application.properties

│       └── static

└── test

    └── java

        └── com.example.restapi

• RestApiApplication.java: The entry point of the Spring Boot application.
• controller/: Contains REST controllers that handle HTTP requests.
• model/: Contains entity classes that represent the data model.
• repository/: Contains interfaces that extend JpaRepository for database interaction.
• service/: Contains the business logic.
• application.properties: Configuration file for the application.

4. Building the REST API

In this section, we’ll build a REST API for managing a simple entity, Product, with fields like id, name, and price. We’ll cover how to create models, repositories, services, and controllers.

Step 1: Creating Models

First, create the Product entity class in the model package:

package com.example.restapi.model;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;

@Entity
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private double price;

    // Getters and Setters
}

• @Entity: Marks the class as a JPA entity.
• @Id: Specifies the primary key.
• @GeneratedValue: Automatically generates the ID value.

Step 2: Creating Repositories

Create the ProductRepository interface in the repository package:

package com.example.restapi.repository;

import com.example.restapi.model.Product;
import org.springframework.data.jpa.repository.JpaRepository;

public interface ProductRepository extends JpaRepository<Product, Long> {
}

• JpaRepository: Provides basic CRUD operations and allows for additional custom queries.

Step 3: Creating Service Layer

The service layer contains the business logic. Create the ProductService class in the service package:

package com.example.restapi.service;

import com.example.restapi.model.Product;
import com.example.restapi.repository.ProductRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;
import java.util.Optional;

@Service
public class ProductService {

    @Autowired
    private ProductRepository productRepository;

    public List<Product> getAllProducts() {
        return productRepository.findAll();
    }

    public Optional<Product> getProductById(Long id) {
        return productRepository.findById(id);
    }

    public Product createProduct(Product product) {
        return productRepository.save(product);
    }

    public Product updateProduct(Long id, Product productDetails) {
        Product product = productRepository.findById(id)
                .orElseThrow(() -> new ResourceNotFoundException("Product not found"));

        product.setName(productDetails.getName());
        product.setPrice(productDetails.getPrice());

        return productRepository.save(product);
    }

    public void deleteProduct(Long id) {
        Product product = productRepository.findById(id)
                .orElseThrow(() -> new ResourceNotFoundException("Product not found"));

        productRepository.delete(product);
    }
}

• @Service: Marks the class as a service component in the Spring context.
• This service class provides methods for all CRUD operations.

Step 4: Creating Controllers

The controller handles HTTP requests and maps them to the appropriate service methods. Create the ProductController class in the controller package:

package com.example.restapi.controller;

import com.example.restapi.model.Product;
import com.example.restapi.service.ProductService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Optional;

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @Autowired
    private ProductService productService;

    @GetMapping
    public List<Product> getAllProducts() {
        return productService.getAllProducts();
    }

    @GetMapping("/{id}")
    public ResponseEntity<Product> getProductById(@PathVariable Long id) {
        Optional<Product> product = productService.getProductById(id);
        return product.map(ResponseEntity::ok)
                .orElseGet(() -> ResponseEntity.notFound().build());
    }

    @PostMapping
    public Product createProduct(@RequestBody Product product) {
        return productService.createProduct(product);
    }

    @PutMapping("/{id}")
    public ResponseEntity<Product> updateProduct(@PathVariable Long id, @RequestBody Product productDetails) {
        Product updatedProduct = productService.updateProduct(id, productDetails);
        return ResponseEntity.ok(updatedProduct);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteProduct(@PathVariable Long id) {
        productService.deleteProduct(id);
        return ResponseEntity.noContent().build();
    }
}

• @RestController: Indicates that this class handles RESTful web services requests.
• @RequestMapping: Maps the base URL for all methods in this controller.
• @GetMapping, @PostMapping, @PutMapping, @DeleteMapping: Handle GET, POST, PUT, and DELETE requests, respectively.

5. Handling HTTP Methods

GET Requests

The @GetMapping annotation handles HTTP GET requests. For example, the getAllProducts() method returns a list of all products:

@GetMapping
public List<Product> getAllProducts() {
    return productService.getAllProducts();
}

To retrieve a specific product by ID:

@GetMapping("/{id}")
public ResponseEntity<Product> getProductById(@PathVariable Long id) {
    Optional<Product> product = productService.getProductById(id);
    return product.map(ResponseEntity::ok)
            .orElseGet(() -> ResponseEntity.notFound().build());
}

POST Requests

The @PostMapping annotation handles HTTP POST requests. The createProduct() method creates a new product:

@PostMapping
public Product createProduct(@RequestBody Product product) {
    return productService.createProduct(product);
}

PUT Requests

The @PutMapping annotation handles HTTP PUT requests. The updateProduct() method updates an existing product:

@PutMapping("/{id}")
public ResponseEntity<Product> updateProduct(@PathVariable Long id, @RequestBody Product productDetails) {
    Product updatedProduct = productService.updateProduct(id, productDetails);
    return ResponseEntity.ok(updatedProduct);
}

DELETE Requests

The @DeleteMapping annotation handles HTTP DELETE requests. The deleteProduct() method deletes a product by ID:

@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteProduct(@PathVariable Long id) {
    productService.deleteProduct(id);
    return ResponseEntity.noContent().build();
}

6. Error Handling in Spring Boot

Effective error handling is crucial for building robust APIs. Spring Boot provides several mechanisms for handling exceptions and returning meaningful responses.

Global Exception Handling

You can use @ControllerAdvice and @ExceptionHandler to create a global exception handler:

package com.example.restapi.exception;

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;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<?> resourceNotFoundException(ResourceNotFoundException ex, WebRequest request) {
        ErrorDetails errorDetails = new ErrorDetails(ex.getMessage(), request.getDescription(false));
        return new ResponseEntity<>(errorDetails, HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<?> globalExceptionHandler(Exception ex, WebRequest request) {
        ErrorDetails errorDetails = new ErrorDetails(ex.getMessage(), request.getDescription(false));
        return new ResponseEntity<>(errorDetails, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

• @ControllerAdvice: A global handler for exceptions thrown by controllers.
• @ExceptionHandler: Maps specific exceptions to handler methods.

Define a custom exception and error details class:

package com.example.restapi.exception;

public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message);
    }
}

package com.example.restapi.exception;

public class ErrorDetails {
    private String message;
    private String details;

    // Constructors, Getters, and Setters
}

7. Securing the API

Security is a crucial aspect of any API. Spring Security provides a comprehensive security framework that can be easily integrated into your Spring Boot application.

Step 1: Add Spring Security Dependency

Add the following dependency in your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

Step 2: Configure Basic Authentication

By default, Spring Security provides basic authentication out of the box. You can configure users and roles in the SecurityConfig class:

package com.example.restapi.config;

import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;

@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.csrf().disable()
            .authorizeRequests()
            .anyRequest().authenticated()
            .and()
            .httpBasic();
        return http.build();
    }

    @Bean
    public UserDetailsService userDetailsService() {
        UserDetails user = User.withDefaultPasswordEncoder()
            .username("user")
            .password("password")
            .roles("USER")
            .build();
        return new InMemoryUserDetailsManager(user);
    }
}

• @EnableWebSecurity: Enables Spring Security's web security support.
• securityFilterChain: Configures HTTP security, including disabling CSRF and enabling basic authentication.
• userDetailsService: Configures an in-memory user with roles.

Explore More: Backend API vs. Frontend API: Understanding the Core Differences

8. Testing the REST API

Testing is a critical part of API development. Spring Boot provides excellent support for testing through the spring-boot-starter-test dependency, which includes libraries like JUnit, Mockito, and Spring Test.

Unit Testing

Unit tests focus on individual components. For example, you can test the ProductService using JUnit and Mockito:

package com.example.restapi.service;

import static org.mockito.Mockito.*;
import static org.junit.jupiter.api.Assertions.*;

import com.example.restapi.model.Product;
import com.example.restapi.repository.ProductRepository;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.MockitoAnnotations;

import java.util.Optional;

class ProductServiceTest {

    @Mock
    private ProductRepository productRepository;

    @InjectMocks
    private ProductService productService;

    @BeforeEach
    void setUp() {
        MockitoAnnotations.openMocks(this);
    }

    @Test
    void testGetProductById() {
        Product product = new Product();
        product.setId(1L);
        product.setName("Test Product");
        product.setPrice(100.0);

        when(productRepository.findById(1L)).thenReturn(Optional.of(product));

        Optional<Product> foundProduct = productService.getProductById(1L);

        assertTrue(foundProduct.isPresent());
        assertEquals("Test Product", foundProduct.get().getName());
    }
}

Integration Testing

Integration tests validate the behavior of the entire application. You can use Spring’s @SpringBootTest annotation to create integration tests:

package com.example.restapi.controller;

import com.example.restapi.model.Product;
import com.example.restapi.repository.ProductRepository;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;

import java.util.List;

import static org.junit.jupiter.api.Assertions.*;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class ProductControllerTest {

    @Autowired
    private TestRestTemplate restTemplate;

    @Autowired
    private ProductRepository productRepository;

    @BeforeEach
    void setUp() {
        productRepository.deleteAll();
    }

    @Test
    void testGetAllProducts() {
        Product product1 = new Product();
        product1.setName("Product 1");
        product1.setPrice(100.0);
        productRepository.save(product1);

        Product product2 = new Product();
        product2.setName("Product 2");
        product2.setPrice(200.0);
        productRepository.save(product2);

        ResponseEntity<List> response = restTemplate.getForEntity("/api/products", List.class);

        assertEquals(HttpStatus.OK, response.getStatusCode());
        assertEquals(2, response.getBody().size());
    }
}

9. Deploying the API

Once your API is developed and tested, you can deploy it to a server. Spring Boot applications are typically packaged as executable JAR files, making deployment straightforward.

Step 1: Build the Project

Use Maven or Gradle to build the project:

bash

mvn clean package

This command generates a JAR file in the target directory.

Step 2: Run the JAR File

You can run the JAR file using the following command (Bash):

bash

java -jar target/restapi-0.0.1-SNAPSHOT.jar

Your application will start, and you can access the API at http://localhost:8080.

Step 3: Deploy to a Cloud Service

You can deploy your Spring Boot application to cloud platforms like AWS, Heroku, or Google Cloud. These platforms provide easy integration and deployment pipelines for Spring Boot applications.

Explore More: Finding the Absolute Difference Value in Java: How-To Guide

Conclusion

Building a REST API using Java Spring Boot is a powerful and efficient way to develop scalable and maintainable web services. In this guide, we've covered the fundamental aspects of building a REST API, including setting up the project, creating models, repositories, services, and controllers, handling HTTP methods, error handling, securing the API, testing, and deployment.

Now, you can create robust RESTful services that can be easily integrated with various client applications. Spring Boot's extensive ecosystem and community support make it an ideal choice for enterprise-grade applications, ensuring that your API is production-ready with minimal effort.

For Java Developers: Join Index.dev, the global talent network connecting senior Java developers with remote projects across the US, UK, and Canada!

For Clients: Hire skilled Java developers within 48 hours to design scalable, high-quality Java solutions for your organization!