Pagination, Sorting and Filtering in Spring Boot REST APIs

//PagingApp.java
package com.javabrahman.rest.paging;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
import java.util.Map;
import java.util.function.Function;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

record Book(long id, String title, String author, int year, BigDecimal price) {
}

// The page envelope returned to clients
record PageResponse<T>(List<T> content, int page, int size, long totalElements, int totalPages) {
}

// Optional filters, bound from query parameters
record BookFilter(String author, Integer fromYear, Integer toYear, BigDecimal maxPrice) {
  boolean matches(Book b) {
    return (author == null || b.author().toLowerCase().contains(author.toLowerCase()))
        && (fromYear == null || b.year() >= fromYear)
        && (toYear == null || b.year() <= toYear)
        && (maxPrice == null || b.price().compareTo(maxPrice) <= 0);
  }
}

@RestController
@RequestMapping("/api/books")
class BookController {
  private static final List<Book> BOOKS = List.of(
      new Book(1, "Effective Java", "Joshua Bloch", 2018, new BigDecimal("45.99")),
      new Book(2, "Java Concurrency in Practice", "Brian Goetz", 2006, new BigDecimal("49.99")),
      new Book(3, "Modern Java in Action", "Raoul-Gabriel Urma", 2018, new BigDecimal("39.99")),
      new Book(4, "Clean Code", "Robert C. Martin", 2008, new BigDecimal("37.49")),
      new Book(5, "Head First Design Patterns", "Eric Freeman", 2020, new BigDecimal("54.99")),
      new Book(6, "Java Puzzlers", "Joshua Bloch", 2005, new BigDecimal("29.99")),
      new Book(7, "Spring in Action", "Craig Walls", 2022, new BigDecimal("49.99")),
      new Book(8, "Refactoring", "Martin Fowler", 2018, new BigDecimal("47.99")),
      new Book(9, "The Pragmatic Programmer", "David Thomas", 2019, new BigDecimal("42.49")),
      new Book(10, "Domain-Driven Design", "Eric Evans", 2003, new BigDecimal("59.99")),
      new Book(11, "Java Performance", "Scott Oaks", 2020, new BigDecimal("44.99")),
      new Book(12, "Effective Unit Testing", "Lasse Koskela", 2013, new BigDecimal("34.99")));

  // Only these fields may be sorted on - never sort by a raw client-supplied name
  private static final Map<String, Comparator<Book>> SORTABLE = Map.of(
      "id", Comparator.comparingLong(Book::id),
      "title", Comparator.comparing(Book::title),
      "year", Comparator.comparingInt(Book::year),
      "price", Comparator.comparing(Book::price));

  @GetMapping
  ResponseEntity<PageResponse<Book>> list(
      @RequestParam(defaultValue = "0") @Min(0) int page,
      @RequestParam(defaultValue = "5") @Min(1) @Max(50) int size,
      @ModelAttribute BookFilter filter,
      WebRequest request) {

    // the raw sort values, each "field" or "field,direction" (see the explanation below)
    String[] sort = request.getParameterValues("sort");
    List<Book> matching = new ArrayList<>(BOOKS.stream().filter(filter::matches).toList());
    matching.sort(comparator(sort == null ? new String[] {"id,asc"} : sort));

    int totalPages = (int) Math.ceil(matching.size() / (double) size);
    int from = Math.min(page * size, matching.size());
    List<Book> content = matching.subList(from, Math.min(from + size, matching.size()));

    return ResponseEntity.ok()
        .header("X-Total-Count", String.valueOf(matching.size()))
        .header("Link", links(page, totalPages))
        .body(new PageResponse<>(content, page, size, matching.size(), totalPages));
  }

  // sort=year,desc&sort=title -> by year descending, then by title ascending
  private Comparator<Book> comparator(String[] sort) {
    Comparator<Book> result = null;
    for (String value : sort) {
      String[] parts = value.split(",");
      String field = parts[0].trim();
      boolean desc = parts.length > 1 && parts[1].trim().equalsIgnoreCase("desc");
      Comparator<Book> c = SORTABLE.get(field);
      if (c == null) {
        throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Cannot sort by '" + field + "'. Sortable fields: " + SORTABLE.keySet().stream().sorted().toList());
      }
      c = desc ? c.reversed() : c;
      result = result == null ? c : result.thenComparing(c);
    }
    return result.thenComparing(Comparator.comparingLong(Book::id));   // a stable order for equal values
  }

  // RFC 8288 Link header: first, prev, next, last
  private String links(int page, int totalPages) {
    Function<Integer, String> url = p -> ServletUriComponentsBuilder.fromCurrentRequest()
        .replaceQueryParam("page", p).build().toUriString();
    List<String> links = new ArrayList<>();
    links.add("<" + url.apply(0) + ">; rel=\"first\"");
    if (page > 0) {   // past the end, prev points to the last real page
      links.add("<" + url.apply(Math.min(page - 1, Math.max(totalPages - 1, 0))) + ">; rel=\"prev\"");
    }
    if (page + 1 < totalPages) {
      links.add("<" + url.apply(page + 1) + ">; rel=\"next\"");
    }
    links.add("<" + url.apply(Math.max(totalPages - 1, 0)) + ">; rel=\"last\"");
    return String.join(", ", links);
  }
}

@SpringBootApplication
public class PagingApp {
  public static void main(String[] args) {
    SpringApplication.run(PagingApp.class, args);
  }
}

@GetMapping
PagedModel<Book> list(@PageableDefault(size = 5, sort = "id") Pageable pageable) {
  return new PagedModel<>(bookRepository.findAll(pageable));   // SELECT ... ORDER BY ... LIMIT ... OFFSET ...
}