Building a Product Catalog API with Pagination, Filtering & Sorting using Spring Boot

Use Case Overview Use Case Overview Imagine you’re building an Product Catalog Service — the core API that powers your online store. Product Catalog Service Your front-end team wants: Products to be listed page by page (not all at once), Filters by category or brand (like “Mobiles” or “Apple”), Sorting by price or name (ascending/descending). Products to be listed page by page (not all at once), listed page by page Filters by category or brand (like “Mobiles” or “Apple”), Filters Sorting by price or name (ascending/descending). Sorting As a backend engineer, your job is to design an efficient REST API that: efficient REST API Handles large datasets efficiently, Supports pagination, filtering, and sorting in one API call, Returns clean, predictable JSON responses. Handles large datasets efficiently, Supports pagination, filtering, and sorting in one API call, pagination filtering sorting Returns clean, predictable JSON responses. A Spring Boot REST API that exposes /api/productsendpoint.This endpoint allows clients (UI, mobile, or other APIs) to: Spring Boot REST API /api/products Get paginated results (e.g., 5 records per page) Sort results (by price, name, etc.) Filter results (by category or brand) So instead of returning thousands of records in one call, it returns smaller, structured, and queryable chunks of data. Get paginated results (e.g., 5 records per page) Get paginated results (e.g., 5 records per page) Sort results (by price, name, etc.) Sort results (by price, name, etc.) Filter results (by category or brand) So instead of returning thousands of records in one call, it returns smaller, structured, and queryable chunks of data. Filter results (by category or brand) So instead of returning thousands of records in one call, it returns smaller, structured, and queryable chunks of data. Why we need Pagination, Filtering, and Sorting Why we need Pagination, Filtering, and Sorting Let’s say your product table has 100,000 products. 100,000 products If you call /api/products without pagination: /api/products The API might take 10–20 seconds. It uses too much memory and bandwidth. The frontend (like React or Angular) can’t render that many rows efficiently. The API might take 10–20 seconds. It uses too much memory and bandwidth. The frontend (like React or Angular) can’t render that many rows efficiently. Pagination → returns results in pages, e.g. /api/products?page=2&size=10Sorting → lets you order results, e.g. /api/products?sort=price,descFiltering → lets you focus results, e.g. /api/products?category=Electronics&brand=Samsung Pagination /api/products?page=2&size=10 Sorting /api/products?sort=price,desc Filtering /api/products?category=Electronics&brand=Samsung You decide to use Java Spring Boot with Spring Data JPA for this — since it gives you built-in power to handle all three. Java Spring Boot Spring Data JPA Solution Architecture Solution Architecture Here’s how the system fits together: Layer Responsibility Entity (Product) Defines product data model Repository Connects to DB and handles queries Service Implements filter + pagination logic Controller Exposes API endpoint DTO (Paged Response) Wraps paginated JSON results H2 Database Lightweight test data storage Layer Responsibility Entity (Product) Defines product data model Repository Connects to DB and handles queries Service Implements filter + pagination logic Controller Exposes API endpoint DTO (Paged Response) Wraps paginated JSON results H2 Database Lightweight test data storage Layer Responsibility Layer Layer Layer Responsibility Responsibility Responsibility Entity (Product) Defines product data model Entity (Product) Entity (Product) Entity (Product) Defines product data model Defines product data model Repository Connects to DB and handles queries Repository Repository Repository Connects to DB and handles queries Connects to DB and handles queries Service Implements filter + pagination logic Service Service Service Implements filter + pagination logic Implements filter + pagination logic Controller Exposes API endpoint Controller Controller Controller Exposes API endpoint Exposes API endpoint DTO (Paged Response) Wraps paginated JSON results DTO (Paged Response) DTO (Paged Response) DTO (Paged Response) Wraps paginated JSON results Wraps paginated JSON results H2 Database Lightweight test data storage H2 Database H2 Database H2 Database Lightweight test data storage Lightweight test data storage Step 1: Setup Your Spring Boot Project Step 1: Setup Your Spring Boot Project Create a Spring Boot project (you can use Spring Initializer) with: Spring Initializer Spring Web Spring Data JPA H2 Database Spring Web Spring Data JPA H2 Database pom.xml pom.xml org.springframework.boot spring-boot-starter org.springframework.boot spring-boot-starter-test test org.springframework.boot spring-boot-starter-data-jpa org.springframework.boot spring-boot-starter-web com.h2database h2 runtime org.projectlombok lombok org.springframework.boot spring-boot-starter org.springframework.boot spring-boot-starter-test test org.springframework.boot spring-boot-starter-data-jpa org.springframework.boot spring-boot-starter-web com.h2database h2 runtime org.projectlombok lombok Step 2: Configure Your Database Step 2: Configure Your Database application.properties ============= H2 Config ============= spring.datasource.url=jdbc:h2:mem:productdb spring.datasource.driverClassName=org.h2.Driver spring.datasource.username=sa spring.datasource.password= spring.h2.console.enabled=true ============= JPA / Hibernate ============= spring.jpa.hibernate.ddl-auto=create spring.jpa.defer-datasource-initialization=true ============= SQL Initialization ============= spring.sql.init.mode=always application.properties ============= H2 Config ============= spring.datasource.url=jdbc:h2:mem:productdb spring.datasource.driverClassName=org.h2.Driver spring.datasource.username=sa spring.datasource.password= spring.h2.console.enabled=true ============= JPA / Hibernate ============= spring.jpa.hibernate.ddl-auto=create spring.jpa.defer-datasource-initialization=true ============= SQL Initialization ============= spring.sql.init.mode=always Step 3: Create the Product Entity Step 3: Create the Product Entity Our API will serve data for a Product object with fields like ID, name, category, brand, and price. import jakarta.persistence.*; import lombok.*; @Entity @Table(name = "products") @Data @NoArgsConstructor @AllArgsConstructor @Builder public class product { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; private String name; private String category; private double price; private String brand; // Constructors public product() {} public product(Long id, String name, String category, String brand, double price) { this.id = id; this.name = name; this.category = category; this.brand = brand; this.price = price; } // Getters & Setters public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getCategory() { return category; } public void setCategory(String category) { this.category = category; } public String getBrand() { return brand; } public void setBrand(String brand) { this.brand = brand; } public double getPrice() { return price; } public void setPrice(double price) { this.price = price; } } import jakarta.persistence.*; import lombok.*; @Entity @Table(name = "products") @Data @NoArgsConstructor @AllArgsConstructor @Builder public class product { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; private String name; private String category; private double price; private String brand; // Constructors public product() {} public product(Long id, String name, String category, String brand, double price) { this.id = id; this.name = name; this.category = category; this.brand = brand; this.price = price; } // Getters & Setters public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getCategory() { return category; } public void setCategory(String category) { this.category = category; } public String getBrand() { return brand; } public void setBrand(String brand) { this.brand = brand; } public double getPrice() { return price; } public void setPrice(double price) { this.price = price; } } Step 4: Define the Repository Step 4: Define the Repository This interface handles all DB communication.Spring Data JPA auto-generates methods based on the name pattern. import com.example.demo.entity.product; import org.springframework.data.domain.*; import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.stereotype.Repository; @Repository public interface ProductRepository extends JpaRepository { // Filter by category Page findByCategoryContainingIgnoreCase(String category, Pageable pageable); Page findByBrandContainingIgnoreCase(String brand, Pageable pageable); } import com.example.demo.entity.product; import org.springframework.data.domain.*; import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.stereotype.Repository; @Repository public interface ProductRepository extends JpaRepository { // Filter by category Page findByCategoryContainingIgnoreCase(String category, Pageable pageable); Page findByBrandContainingIgnoreCase(String brand, Pageable pageable); } **Why this matters: \ These methods let you query by category or brand dynamically, without writing SQL. Step 5: Implement the Service Layer Step 5: Implement the Service Layer This layer applies business logic — i.e., which filter to apply and how to paginate. import com.example.demo.entity.product; import com.example.demo.repository.ProductRepository; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.data.domain.*; import org.springframework.stereotype.Service; @Service public class ProductService { @Autowired private ProductRepository productRepository; public Page getAllProducts(String category, String brand, Pageable pageable) { if (category != null && !category.isEmpty()) { return productRepository.findByCategoryContainingIgnoreCase(category, pageable); } else if (brand != null && !brand.isEmpty()) { return productRepository.findByBrandContainingIgnoreCase(brand, pageable); } else { return productRepository.findAll(pageable); } } } import com.example.demo.entity.product; import com.example.demo.repository.ProductRepository; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.data.domain.*; import org.springframework.stereotype.Service; @Service public class ProductService { @Autowired private ProductRepository productRepository; public Page getAllProducts(String category, String brand, Pageable pageable) { if (category != null && !category.isEmpty()) { return productRepository.findByCategoryContainingIgnoreCase(category, pageable); } else if (brand != null && !brand.isEmpty()) { return productRepository.findByBrandContainingIgnoreCase(brand, pageable); } else { return productRepository.findAll(pageable); } } } Step 6: Build the Controller (Main API Endpoint) Step 6: Build the Controller (Main API Endpoint) This endpoint: Accepts query parameters (page, size, sort, category, brand) Converts them to a Page Request Calls the service Returns a Paged Response DTO import com.example.demo.dto.PagedResponse; import com.example.demo.entity.product; import com.example.demo.service.ProductService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.data.domain.*; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/products") public class ProductController { @Autowired private ProductService productService; @GetMapping public PagedResponse getAllProducts( @RequestParam(defaultValue = "0") int page, @RequestParam(defaultValue = "5") int size, @RequestParam(defaultValue = "id,asc") String[] sort, @RequestParam(required = false) String category, @RequestParam(required = false) String brand) { // Handle sorting (field and direction) String sortField = sort[0]; Sort.Direction direction = (sort.length > 1 && sort[1].equalsIgnoreCase("desc")) ? Sort.Direction.DESC : Sort.Direction.ASC; Pageable pageable = PageRequest.of(page, size, Sort.by(direction, sortField)); Page productPage = productService.getAllProducts(category, brand, pageable); return new PagedResponse ( productPage.getContent(), productPage.getNumber(), productPage.getSize(), productPage.getTotalElements(), productPage.getTotalPages(), productPage.isLast() ); } } Accepts query parameters (page, size, sort, category, brand) Accepts query parameters (page, size, sort, category, brand) Converts them to a Page Request Converts them to a Page Request Page Request Calls the service Calls the service Returns a Paged Response DTO import com.example.demo.dto.PagedResponse; import com.example.demo.entity.product; import com.example.demo.service.ProductService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.data.domain.*; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/products") public class ProductController { @Autowired private ProductService productService; @GetMapping public PagedResponse getAllProducts( @RequestParam(defaultValue = "0") int page, @RequestParam(defaultValue = "5") int size, @RequestParam(defaultValue = "id,asc") String[] sort, @RequestParam(required = false) String category, @RequestParam(required = false) String brand) { // Handle sorting (field and direction) String sortField = sort[0]; Sort.Direction direction = (sort.length > 1 && sort[1].equalsIgnoreCase("desc")) ? Sort.Direction.DESC : Sort.Direction.ASC; Pageable pageable = PageRequest.of(page, size, Sort.by(direction, sortField)); Page productPage = productService.getAllProducts(category, brand, pageable); return new PagedResponse ( productPage.getContent(), productPage.getNumber(), productPage.getSize(), productPage.getTotalElements(), productPage.getTotalPages(), productPage.isLast() ); } } Returns a Paged Response DTO Paged Response DTO import com.example.demo.dto.PagedResponse; import com.example.demo.entity.product; import com.example.demo.service.ProductService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.data.domain.*; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/products") public class ProductController { @Autowired private ProductService productService; @GetMapping public PagedResponse getAllProducts( @RequestParam(defaultValue = "0") int page, @RequestParam(defaultValue = "5") int size, @RequestParam(defaultValue = "id,asc") String[] sort, @RequestParam(required = false) String category, @RequestParam(required = false) String brand) { // Handle sorting (field and direction) String sortField = sort[0]; Sort.Direction direction = (sort.length > 1 && sort[1].equalsIgnoreCase("desc")) ? Sort.Direction.DESC : Sort.Direction.ASC; Pageable pageable = PageRequest.of(page, size, Sort.by(direction, sortField)); Page productPage = productService.getAllProducts(category, brand, pageable); return new PagedResponse ( productPage.getContent(), productPage.getNumber(), productPage.getSize(), productPage.getTotalElements(), productPage.getTotalPages(), productPage.isLast() ); } } import com.example.demo.dto.PagedResponse; import com.example.demo.entity.product; import com.example.demo.service.ProductService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.data.domain.*; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/products") public class ProductController { @Autowired private ProductService productService; @GetMapping public PagedResponse getAllProducts( @RequestParam(defaultValue = "0") int page, @RequestParam(defaultValue = "5") int size, @RequestParam(defaultValue = "id,asc") String[] sort, @RequestParam(required = false) String category, @RequestParam(required = false) String brand) { // Handle sorting (field and direction) String sortField = sort[0]; Sort.Direction direction = (sort.length > 1 && sort[1].equalsIgnoreCase("desc")) ? Sort.Direction.DESC : Sort.Direction.ASC; Pageable pageable = PageRequest.of(page, size, Sort.by(direction, sortField)); Page productPage = productService.getAllProducts(category, brand, pageable); return new PagedResponse ( productPage.getContent(), productPage.getNumber(), productPage.getSize(), productPage.getTotalElements(), productPage.getTotalPages(), productPage.isLast() ); } } Step 7: Create a Paged Response DTO We wrap our paginated results in a DTO for consistent JSON structure. import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor; import java.util.List; @Data @AllArgsConstructor @NoArgsConstructor public class PagedResponse { private List content; private int pageNumber; private int pageSize; private long totalElements; private int totalPages; private boolean last; public PagedResponse(List content, int pageNumber, int pageSize, long totalElements, int totalPages, boolean last) { this.content = content; this.pageNumber = pageNumber; this.pageSize = pageSize; this.totalElements = totalElements; this.totalPages = totalPages; this.last = last; } // Getters and setters public List getContent() { return content; } public void setContent(List content) { this.content = content; } public int getPageNumber() { return pageNumber; } public void setPageNumber(int pageNumber) { this.pageNumber = pageNumber; } public int getPageSize() { return pageSize; } public void setPageSize(int pageSize) { this.pageSize = pageSize; } public long getTotalElements() { return totalElements; } public void setTotalElements(long totalElements) { this.totalElements = totalElements; } public int getTotalPages() { return totalPages; } public void setTotalPages(int totalPages) { this.totalPages = totalPages; } public boolean isLast() { return last; } public void setLast(boolean last) { this.last = last; } } import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor; import java.util.List; @Data @AllArgsConstructor @NoArgsConstructor public class PagedResponse { private List content; private int pageNumber; private int pageSize; private long totalElements; private int totalPages; private boolean last; public PagedResponse(List content, int pageNumber, int pageSize, long totalElements, int totalPages, boolean last) { this.content = content; this.pageNumber = pageNumber; this.pageSize = pageSize; this.totalElements = totalElements; this.totalPages = totalPages; this.last = last; } // Getters and setters public List getContent() { return content; } public void setContent(List content) { this.content = content; } public int getPageNumber() { return pageNumber; } public void setPageNumber(int pageNumber) { this.pageNumber = pageNumber; } public int getPageSize() { return pageSize; } public void setPageSize(int pageSize) { this.pageSize = pageSize; } public long getTotalElements() { return totalElements; } public void setTotalElements(long totalElements) { this.totalElements = totalElements; } public int getTotalPages() { return totalPages; } public void setTotalPages(int totalPages) { this.totalPages = totalPages; } public boolean isLast() { return last; } public void setLast(boolean last) { this.last = last; } } Step 8: Initialize Sample Data Automatically Step 8: Initialize Sample Data Automatically Instead of manually inserting data, let’s pre-load it when the app starts. import com.example.demo.entity.product; import com.example.demo.repository.ProductRepository; import org.springframework.boot.CommandLineRunner; import org.springframework.stereotype.Component; @Component public class DataInitializer implements CommandLineRunner { private final ProductRepository repository; public DataInitializer(ProductRepository repository) { this.repository = repository; } @Override public void run(String... args) { repository.save(new product(null, "iPhone 15", "Mobile", "Apple", 999.99)); repository.save(new product(null, "Galaxy S23", "Mobile", "Samsung", 899.99)); repository.save(new product(null, "MacBook Air", "Laptop", "Apple", 1299.00)); repository.save(new product(null, "ThinkPad X1", "Laptop", "Lenovo", 1399.00)); repository.save(new product(null, "OnePlus 12", "Mobile", "OnePlus", 749.99)); repository.save(new product(null, "Sony Bravia 55\"", "TV", "Sony", 1099.00)); repository.save(new product(null, "iPad Air", "Tablet", "Apple", 599.00)); } } import com.example.demo.entity.product; import com.example.demo.repository.ProductRepository; import org.springframework.boot.CommandLineRunner; import org.springframework.stereotype.Component; @Component public class DataInitializer implements CommandLineRunner { private final ProductRepository repository; public DataInitializer(ProductRepository repository) { this.repository = repository; } @Override public void run(String... args) { repository.save(new product(null, "iPhone 15", "Mobile", "Apple", 999.99)); repository.save(new product(null, "Galaxy S23", "Mobile", "Samsung", 899.99)); repository.save(new product(null, "MacBook Air", "Laptop", "Apple", 1299.00)); repository.save(new product(null, "ThinkPad X1", "Laptop", "Lenovo", 1399.00)); repository.save(new product(null, "OnePlus 12", "Mobile", "OnePlus", 749.99)); repository.save(new product(null, "Sony Bravia 55\"", "TV", "Sony", 1099.00)); repository.save(new product(null, "iPad Air", "Tablet", "Apple", 599.00)); } } Step 9: Run and Test Step 9: Run and Test Start your application: Run As à Java Application Run As à Java Application and start the Application, once the Application Started. Now test the endpoints: Description URL Get first page (3 items) http://localhost:8080/api/products?page=0&size=3 Sort by price descending http://localhost:8080/api/products?sort=price,desc Filter by category http://localhost:8080/api/products?category=Mobile Filter by brand http://localhost:8080/api/products?brand=Apple Combine filter + sort http://localhost:8080/api/products?category=Laptop&sort=price,asc Description URL Get first page (3 items) http://localhost:8080/api/products?page=0&size=3 Sort by price descending http://localhost:8080/api/products?sort=price,desc Filter by category http://localhost:8080/api/products?category=Mobile Filter by brand http://localhost:8080/api/products?brand=Apple Combine filter + sort http://localhost:8080/api/products?category=Laptop&sort=price,asc Description URL Description Description Description URL URL URL Get first page (3 items) http://localhost:8080/api/products?page=0&size=3 Get first page (3 items) Get first page (3 items) http://localhost:8080/api/products?page=0&size=3 http://localhost:8080/api/products?page=0&size=3 http://localhost:8080/api/products?page=0&size=3 Sort by price descending http://localhost:8080/api/products?sort=price,desc Sort by price descending Sort by price descending http://localhost:8080/api/products?sort=price,desc http://localhost:8080/api/products?sort=price,desc http://localhost:8080/api/products?sort=price,desc Filter by category http://localhost:8080/api/products?category=Mobile Filter by category Filter by category http://localhost:8080/api/products?category=Mobile http://localhost:8080/api/products?category=Mobile http://localhost:8080/api/products?category=Mobile Filter by brand http://localhost:8080/api/products?brand=Apple Filter by brand Filter by brand http://localhost:8080/api/products?brand=Apple http://localhost:8080/api/products?brand=Apple http://localhost:8080/api/products?brand=Apple Combine filter + sort http://localhost:8080/api/products?category=Laptop&sort=price,asc Combine filter + sort Combine filter + sort http://localhost:8080/api/products?category=Laptop&sort=price,asc http://localhost:8080/api/products?category=Laptop&sort=price,asc http://localhost:8080/api/products?category=Laptop&sort=price,asc Sample Output Sample Output { "content": [ { "id": 8, "name": "iPhone 15", "category": "Mobile", "price": 999.99, "brand": "Apple" }, { "id": 9, "name": "Galaxy S23", "category": "Mobile", "price": 899.99, "brand": "Samsung" }, { "id": 12, "name": "OnePlus 12", "category": "Mobile", "price": 749.99, "brand": "OnePlus" } ], "pageNumber": 0, "pageSize": 5, "totalElements": 3, "totalPages": 1, "last": true } { "content": [ { "id": 8, "name": "iPhone 15", "category": "Mobile", "price": 999.99, "brand": "Apple" }, { "id": 9, "name": "Galaxy S23", "category": "Mobile", "price": 899.99, "brand": "Samsung" }, { "id": 12, "name": "OnePlus 12", "category": "Mobile", "price": 749.99, "brand": "OnePlus" } ], "pageNumber": 0, "pageSize": 5, "totalElements": 3, "totalPages": 1, "last": true } This gives the frontend everything it needs to build a table with pagination buttons: frontend everything it needs content → actual records to show pageNumber and pageSize → which page user is viewing totalElements and totalPages → how many total records exist last → flag if this is the last page content → actual records to show content pageNumber and pageSize → which page user is viewing pageNumber pageSize totalElements and totalPages → how many total records exist totalElements totalPages last → flag if this is the last page last Technical Insight (How Spring Does This) Technical Insight (How Spring Does This) The magic is done by Pageable and Page interfaces in Spring Data JPA. They inject LIMIT, OFFSET, and ORDER BY automatically in SQL. @RequestParam parsing lets users dynamically control the query without changing backend code. The magic is done by Pageable and Page interfaces in Spring Data JPA. Pageable Page Spring Data JPA They inject LIMIT, OFFSET, and ORDER BY automatically in SQL. LIMIT OFFSET ORDER BY @RequestParam parsing lets users dynamically control the query without changing backend code. @RequestParam Why This Matters (Real-World Context) Why This Matters (Real-World Context) This same pattern is used in: E-Commerce: Paginating thousands of products Admin Dashboards: Listing users, orders, logs Microservices: Returning partial results efficiently E-Commerce: Paginating thousands of products E-Commerce Admin Dashboards: Listing users, orders, logs Admin Dashboards Microservices: Returning partial results efficiently Microservices Conclusion Conclusion With this use case, you’ve mastered: Pagination and sorting with Spring Data JPA Clean JSON responses with DTOs Auto data initialization Efficient filtering logic Pagination and sorting with Spring Data JPA Clean JSON responses with DTOs Auto data initialization Efficient filtering logic This setup forms the backbone of any enterprise API that needs to handle data efficiently while remaining scalable and maintainable. enterprise API