Request Parameters in Spring Boot

REST APIs receive data through URL paths, query strings, request bodies, and headers. This chapter covers every way to extract data from HTTP requests.

---

@PathVariable — From URL Path

// GET /api/books/42
@GetMapping("/{id}")
public Book getById(@PathVariable Long id) {
    return bookService.findById(id);
}

// GET /api/authors/5/books
@GetMapping("/authors/{authorId}/books")
public List<Book> getByAuthor(@PathVariable Long authorId) {
    return bookService.findByAuthorId(authorId);
}

// Multiple path variables
// GET /api/shelves/3/books/42
@GetMapping("/shelves/{shelfId}/books/{bookId}")
public Book getBook(@PathVariable Long shelfId, @PathVariable Long bookId) {
    return bookService.findByShelfAndId(shelfId, bookId);
}

---

@RequestParam — From Query String

// GET /api/books?author=Martin
@GetMapping
public List<Book> search(@RequestParam String author) {
    return bookService.findByAuthor(author);
}

// Optional with default
// GET /api/books?page=0&size=20&sort=title
@GetMapping
public List<Book> getAll(
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "20") int size,
    @RequestParam(defaultValue = "title") String sort
) {
    return bookService.findAll(page, size, sort);
}

// Optional parameter
// GET /api/books or GET /api/books?category=fiction
@GetMapping
public List<Book> getAll(
    @RequestParam(required = false) String category
) {
    if (category != null) {
        return bookService.findByCategory(category);
    }
    return bookService.findAll();
}

---

@RequestBody — From Request Body

// POST /api/books
// Body: {"title":"Clean Code","author":"Robert Martin","price":39.99}
@PostMapping
public ResponseEntity<BookResponse> create(@RequestBody CreateBookRequest request) {
    Book book = bookService.create(request);
    return ResponseEntity.created(URI.create("/api/books/" + book.getId()))
        .body(BookResponse.from(book));
}

public record CreateBookRequest(
    String title,
    String author,
    String isbn,
    BigDecimal price
) {}

---

@RequestHeader — From HTTP Headers

@GetMapping
public List<Book> getAll(
    @RequestHeader("Accept-Language") String language,
    @RequestHeader(value = "X-Request-ID", required = false) String requestId
) {
    // Use language for localization, requestId for tracing
    return bookService.findAll();
}

---

Pagination with Pageable

Spring Data provides built-in pagination:

@GetMapping
public Page<BookResponse> getAll(Pageable pageable) {
    return bookService.findAll(pageable);
}

# Page 0, 10 items, sorted by title ascending
GET /api/books?page=0&size=10&sort=title,asc

# Sorted by price descending
GET /api/books?page=0&size=20&sort=price,desc

# Multiple sort fields
GET /api/books?sort=author,asc&sort=title,asc

Service layer:

@Service
public class BookService {

    public Page<BookResponse> findAll(Pageable pageable) {
        return bookRepository.findAll(pageable)
            .map(BookResponse::from);
    }
}

Response:

{
  "content": [
    {"id": 1, "title": "Clean Code", "author": "Robert Martin"},
    {"id": 2, "title": "Effective Java", "author": "Joshua Bloch"}
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "totalElements": 42,
  "totalPages": 5,
  "last": false
}

---

Default Pagination Config

spring:
  data:
    web:
      pageable:
        default-page-size: 20
        max-page-size: 100

---

Combining Parameters

@GetMapping("/search")
public Page<BookResponse> search(
    @RequestParam(required = false) String title,
    @RequestParam(required = false) String author,
    @RequestParam(required = false) BigDecimal minPrice,
    @RequestParam(required = false) BigDecimal maxPrice,
    Pageable pageable
) {
    return bookService.search(title, author, minPrice, maxPrice, pageable);
}

GET /api/books/search?author=Martin&minPrice=20&page=0&size=10&sort=price,asc

---

Key Takeaways

1. @PathVariable for resource identifiers in the URL path.
2. @RequestParam for filters, search, and optional parameters.
3. @RequestBody for POST/PUT payloads (JSON deserialized to object).
4. Pageable auto-handles page, size, sort query parameters.
5. Set defaultValue and required = false for optional params.

---

What’s Next?

Next: Bean Validation — @Valid, @NotNull, @Size, and custom validators.