Handling path variables and query params together in Spring Boot - Deep Dive

Overview - Handling path variables and query params together

What is it?

Handling path variables and query parameters together means writing code that can read values from both the URL path and the URL query string in a web request. Path variables are parts of the URL that act like placeholders for values, while query parameters come after a question mark and provide extra information. In Spring Boot, you can easily get both types of values in your controller methods to customize responses. This helps build flexible web APIs that respond differently based on user input.

Why it matters

Without handling both path variables and query parameters, web applications would be limited in how they accept input from users. Path variables let you identify specific resources, like a user ID, while query parameters let you filter or modify the request, like sorting or paging. Together, they make APIs more powerful and user-friendly. If this concept didn't exist, developers would struggle to build clear and flexible URLs, making apps harder to use and maintain.

Where it fits

Before learning this, you should understand basic Spring Boot controllers and how to handle simple requests. You should also know what URLs and HTTP requests are. After mastering this, you can learn about request bodies, form data, and advanced request handling like validation and error handling.

Mental Model

Core Idea

Path variables pick out the main resource from the URL path, while query parameters add extra options or filters to the request.

Think of it like...

It's like ordering a pizza: the path variable is the pizza size you choose (small, medium, large), and the query parameters are the extra toppings you add on top.

URL structure:

  https://example.com/orders/{orderId}?status=delivered&sort=date

  ┌───────────────┐  ┌─────────────────────────────┐
  │ Path Variable │  │       Query Parameters       │
  │   orderId     │  │ status=delivered, sort=date │
  └───────────────┘  └─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Path Variables Basics

Concept: Learn what path variables are and how to extract them in Spring Boot.

In Spring Boot, path variables are parts of the URL path marked with curly braces {} in the @GetMapping or other mapping annotations. You use @PathVariable in the method parameters to get their values. Example: @GetMapping("/users/{id}") public String getUser(@PathVariable String id) { return "User ID: " + id; }

Result

When you visit /users/123, the method receives "123" as the id and returns "User ID: 123".

Understanding path variables is key because they let you identify specific resources directly from the URL path, making URLs clean and meaningful.

2

Foundation

Understanding Query Parameters Basics

Concept: Learn what query parameters are and how to read them in Spring Boot.

Query parameters come after a question mark (?) in the URL and provide extra information. In Spring Boot, you use @RequestParam to get their values. Example: @GetMapping("/search") public String search(@RequestParam String keyword) { return "Searching for: " + keyword; }

Result

Visiting /search?keyword=books returns "Searching for: books".

Query parameters let users add extra options or filters to requests without changing the main URL path.

3

Intermediate

Combining Path Variables and Query Params

🤔Before reading on: do you think you can use @PathVariable and @RequestParam together in the same method? Commit to your answer.

Concept: Learn how to handle both path variables and query parameters in one controller method.

You can combine @PathVariable and @RequestParam in the same method to get values from both the URL path and query string. Example: @GetMapping("/products/{category}") public String getProducts( @PathVariable String category, @RequestParam(required = false) String sort) { return "Category: " + category + ", Sort by: " + (sort != null ? sort : "default"); }

Result

Visiting /products/electronics?sort=price returns "Category: electronics, Sort by: price". Visiting /products/electronics returns "Category: electronics, Sort by: default".

Knowing you can mix these two lets you build flexible APIs that identify resources and customize responses in one call.

4

Intermediate

Handling Optional Query Parameters

🤔Before reading on: do you think query parameters must always be provided? Commit to your answer.

Concept: Learn how to make query parameters optional and provide default values.

By default, @RequestParam is required. You can make it optional by setting required=false and provide a defaultValue. Example: @GetMapping("/items/{id}") public String getItem( @PathVariable String id, @RequestParam(required = false, defaultValue = "asc") String order) { return "Item: " + id + ", Order: " + order; }

Result

Visiting /items/5?order=desc returns "Item: 5, Order: desc". Visiting /items/5 returns "Item: 5, Order: asc".

Handling optional query parameters improves user experience by providing sensible defaults and avoiding errors.

5

Advanced

Validating and Binding Multiple Query Parameters

🤔Before reading on: can you bind multiple query parameters into a single object automatically? Commit to your answer.

Concept: Learn how to bind multiple query parameters into a Java object using @ModelAttribute for cleaner code.

Instead of listing many @RequestParam, you can create a class with fields matching query parameters and use @ModelAttribute. Example: public class Filter { private String color; private Integer size; // getters and setters } @GetMapping("/products/{type}") public String filterProducts( @PathVariable String type, @ModelAttribute Filter filter) { return "Type: " + type + ", Color: " + filter.getColor() + ", Size: " + filter.getSize(); }

Result

Visiting /products/shoes?color=red&size=42 returns "Type: shoes, Color: red, Size: 42".

Binding query parameters into objects simplifies method signatures and scales better for many parameters.

6

Advanced

Handling Path Variables and Query Params in REST APIs

🤔Before reading on: do you think mixing path variables and query params affects REST API design? Commit to your answer.

Concept: Understand best practices for using path variables and query parameters in RESTful APIs.

Path variables should identify the resource hierarchy (like /users/{id}), while query parameters should filter, sort, or paginate results. Example: @GetMapping("/users/{userId}/orders") public String getUserOrders( @PathVariable String userId, @RequestParam(required = false) Integer page, @RequestParam(required = false) Integer size) { return "User: " + userId + ", Page: " + page + ", Size: " + size; }

Result

Visiting /users/10/orders?page=2&size=5 returns "User: 10, Page: 2, Size: 5".

Knowing REST principles helps you design clear URLs that separate resource identity from query options.

7

Expert

Common Pitfalls and Performance Considerations

🤔Before reading on: do you think handling many query parameters can impact performance or cause bugs? Commit to your answer.

Concept: Learn about subtle issues like missing parameters, type mismatches, and performance when handling many path variables and query params.

If query parameters are missing or have wrong types, Spring Boot throws errors unless handled carefully. Also, large numbers of parameters can slow parsing. Use @RequestParam with defaultValue or Optional<> to avoid errors. Example: @GetMapping("/search/{type}") public String search( @PathVariable String type, @RequestParam Optional page) { int currentPage = page.orElse(1); return "Type: " + type + ", Page: " + currentPage; }

Result

Visiting /search/book returns "Type: book, Page: 1" without error. Visiting /search/book?page=abc causes error if not handled.

Understanding error handling and defaults prevents runtime failures and improves API robustness.

Under the Hood

Spring Boot uses the DispatcherServlet to route HTTP requests to controller methods. It parses the URL path and query string separately. Path variables are extracted by matching the URL pattern in @RequestMapping annotations. Query parameters are parsed from the URL after the question mark. Spring uses argument resolvers to inject these values into method parameters annotated with @PathVariable and @RequestParam. It also performs type conversion and validation during this process.

Why designed this way?

Separating path variables and query parameters follows HTTP and REST conventions, making URLs meaningful and flexible. This design allows clear resource identification via path variables and optional modifiers via query parameters. Spring Boot's annotation-based approach simplifies binding these values, reducing boilerplate and improving readability. Alternatives like manual parsing were error-prone and verbose, so this declarative style was chosen for developer productivity.

┌───────────────────────────────┐
│        HTTP Request URL        │
│ /users/123/orders?page=2&size=5│
└─────────────┬─────────────────┘
              │
   ┌──────────┴───────────┐
   │                      │
┌─────────┐            ┌─────────────┐
│ Path    │            │ Query Params│
│ Variable│            │ page=2,size=5│
└─────────┘            └─────────────┘
   │                      │
   │                      │
┌───────────────┐    ┌───────────────┐
│@PathVariable  │    │ @RequestParam  │
│  userId=123   │    │ page=2,size=5 │
└───────────────┘    └───────────────┘
          │                  │
          └───────┬──────────┘
                  │
          ┌───────────────────┐
          │ Controller Method │
          └───────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think @RequestParam can extract values from the URL path? Commit to yes or no.

Common Belief: Some people believe @RequestParam can get values from the URL path segments.

Reality: @RequestParam only extracts values from the query string, not the path. Path variables require @PathVariable.

Why it matters: Using @RequestParam for path values causes runtime errors or null values, breaking the API.

Quick: Do you think path variables can be optional by default? Commit to yes or no.

Common Belief: Many think path variables can be optional like query parameters.

Reality: Path variables are required by default and cannot be optional because they define the URL structure.

Why it matters: Trying to make path variables optional leads to confusing URL mappings and errors.

Quick: Do you think query parameters must always be strings? Commit to yes or no.

Common Belief: People often believe query parameters are always strings and must be manually converted.

Reality: Spring Boot automatically converts query parameters to many types like int, boolean, enums if method parameter types match.

Why it matters: Not knowing this leads to unnecessary manual parsing and more complex code.

Quick: Do you think mixing many query parameters slows down the server significantly? Commit to yes or no.

Common Belief: Some assume that many query parameters cause big performance hits.

Reality: Parsing query parameters is lightweight; performance issues usually come from business logic, not parameter parsing.

Why it matters: Worrying about query param parsing performance can distract from real bottlenecks.

Expert Zone

1

Spring Boot resolves path variables before query parameters, so overlapping names can cause confusion if not carefully named.

2

Using @RequestParam Map lets you capture all query parameters dynamically, useful for flexible filters.

3

@MatrixVariable is a rarely used alternative to query params that encodes parameters in path segments, but it requires special configuration.

When NOT to use

Avoid using path variables for optional or filter-like data; use query parameters instead. For complex filtering, consider request bodies with POST instead of many query parameters. If you need hierarchical resource identification, use nested path variables carefully to avoid ambiguous mappings.

Production Patterns

In real APIs, path variables identify resources (e.g., /users/{id}), while query parameters handle pagination, sorting, and filtering (e.g., ?page=2&sort=name). Controllers often combine @PathVariable with @RequestParam and bind query params to objects with @ModelAttribute for clean code. Validation annotations ensure parameters meet requirements before processing.

Connections

REST API Design

Builds-on

Understanding how to handle path variables and query parameters is essential to designing clear and intuitive RESTful URLs that separate resource identity from optional modifiers.

HTTP Protocol

Same pattern

Path variables and query parameters directly map to parts of the HTTP URL, so knowing HTTP URL structure helps understand how web frameworks extract these values.

Database Query Filtering

Builds-on

Query parameters often translate into database filters or sorting options, so understanding this connection helps design APIs that efficiently query data.

Common Pitfalls

#1 Confusing @PathVariable with @RequestParam annotations.

Wrong approach:

@GetMapping("/users/{id}")
public String getUser(@RequestParam String id) {
return id;
}

Correct approach:

@GetMapping("/users/{id}")
public String getUser(@PathVariable String id) {
return id;
}

Root cause:

Misunderstanding that @RequestParam reads query parameters, not path variables.

#2 Not handling optional query parameters causing errors when missing.

Wrong approach:

@GetMapping("/items")
public String getItems(@RequestParam String filter) {
return filter;
}

Correct approach:

@GetMapping("/items")
public String getItems(@RequestParam(required = false, defaultValue = "all") String filter) {
return filter;
}

Root cause:

Assuming query parameters are always present without defaults or optional flags.

#3 Using path variables for filtering or optional data.

Wrong approach:

@GetMapping("/products/{color}")
public String getProducts(@PathVariable String color) {
return color;
}

Correct approach:

@GetMapping("/products")
public String getProducts(@RequestParam(required = false) String color) {
return color != null ? color : "all";
}

Root cause:

Misusing path variables for data that should be optional or filter-like.

Key Takeaways

Path variables identify specific resources in the URL path and are required parts of the URL.

Query parameters provide optional extra information after the URL path and can be optional with defaults.

Spring Boot uses @PathVariable and @RequestParam annotations to extract these values cleanly in controller methods.

Combining path variables and query parameters allows building flexible and user-friendly web APIs.

Proper handling of these inputs, including validation and defaults, prevents errors and improves API robustness.

Practice

1. In Spring Boot, which annotation is used to extract a value from the URL path segment in a controller method?

easy

A. @PathVariable

B. @RequestParam

C. @RequestBody

D. @RequestHeader

Solution

1. Step 1: Understand URL parts

   The URL path segment is the part of the URL that defines the resource location, like /users/{id}.

2. Step 2: Identify the correct annotation

   @PathVariable is used to bind a method parameter to a URI template variable in the path.

3. Final Answer:

   @PathVariable -> Option A

4. Quick Check:

   Path segment value = @PathVariable [OK]

Hint: Use @PathVariable for URL path parts, not query strings [OK]

Common Mistakes:

• Confusing @RequestParam with @PathVariable
• Using @RequestBody for path variables
• Trying to get path variables from headers

2. Which of the following method signatures correctly handles a path variable id and a query parameter sort in Spring Boot?

easy

A. public String getUser(@PathVariable String id, @RequestParam String sort)

B. public String getUser(@RequestParam String id, @PathVariable String sort)

C. public String getUser(@RequestParam String id, @RequestParam String sort)

D. public String getUser(@PathVariable String id, @PathVariable String sort)

Solution

1. Step 1: Match annotations to parameter types

   Path variables come from the URL path, so use @PathVariable for id. Query parameters come after ?, so use @RequestParam for sort.

2. Step 2: Check method signature correctness

   public String getUser(@PathVariable String id, @RequestParam String sort) correctly uses @PathVariable for id and @RequestParam for sort.

3. Final Answer:

   public String getUser(@PathVariable String id, @RequestParam String sort) -> Option A

4. Quick Check:

   Path variable = @PathVariable, Query param = @RequestParam [OK]

Hint: Path variables use @PathVariable, query params use @RequestParam [OK]

Common Mistakes:

• Swapping @PathVariable and @RequestParam
• Using @PathVariable for query parameters
• Missing one of the annotations

3. Given the controller method:

@GetMapping("/items/{itemId}")
public String getItem(@PathVariable String itemId, @RequestParam(defaultValue = "asc") String order) {
    return itemId + "-" + order;
}

What will be the output when a client requests /items/42?order=desc?

medium

A. "42-asc"

B. "42-desc"

C. "desc-42"

D. Runtime error due to missing parameter

Solution

1. Step 1: Identify values from URL

   Path variable itemId is "42" from /items/42. Query parameter order is "desc" from ?order=desc.

2. Step 2: Understand method return

   The method returns itemId + "-" + order, so "42-desc".

3. Final Answer:

   "42-desc" -> Option B

4. Quick Check:

   Path variable + query param = "42-desc" [OK]

Hint: Path variable fills {itemId}, query param fills order value [OK]

Common Mistakes:

• Ignoring query parameter and using default
• Mixing order of concatenation
• Expecting error when query param is present

4. Consider this controller method:

@GetMapping("/books/{bookId}")
public String getBook(@PathVariable int bookId, @RequestParam int page) {
    return "Book: " + bookId + ", Page: " + page;
}

What error will occur if a client calls /books/abc?page=2?

medium

A. 404 Not Found because path variable missing

B. 500 Internal Server Error due to null page

C. 400 Bad Request due to type mismatch

D. No error, returns "Book: abc, Page: 2"

Solution

1. Step 1: Check path variable type

   The method expects bookId as int, but URL provides "abc" which is not a number.

2. Step 2: Understand Spring Boot behavior on type mismatch

   Spring Boot returns 400 Bad Request when it cannot convert path variable to required type.

3. Final Answer:

   400 Bad Request due to type mismatch -> Option C

4. Quick Check:

   Type mismatch in @PathVariable causes 400 error [OK]

Hint: Non-numeric path variable for int causes 400 error [OK]

Common Mistakes:

• Expecting 404 Not Found instead of 400
• Assuming null page causes error
• Thinking method returns string with invalid input

5. You want to create a Spring Boot endpoint that handles a user ID as a path variable and optionally accepts a query parameter filter. If filter is missing, it should default to "all". Which method signature correctly implements this behavior?

hard

A. public String getUser(@PathVariable String userId, @RequestParam Optional<String> filter)

B. public String getUser(@RequestParam String userId, @RequestParam String filter)

C. public String getUser(@PathVariable String userId, @RequestParam(required = true) String filter)

D. public String getUser(@PathVariable String userId, @RequestParam(defaultValue = "all") String filter)

Solution

1. Step 1: Identify path variable usage

   User ID is part of the URL path, so use @PathVariable for userId.

2. Step 2: Handle optional query parameter with default

   Use @RequestParam with defaultValue = "all" to provide a default when filter is missing.

3. Final Answer:

   public String getUser(@PathVariable String userId, @RequestParam(defaultValue = "all") String filter) -> Option D

4. Quick Check:

   Default query param value = @RequestParam(defaultValue) [OK]

Hint: Use @RequestParam(defaultValue) for optional query params [OK]

Common Mistakes:

• Using @RequestParam(required = true) for optional params
• Using @RequestParam without defaultValue causing errors
• Confusing @RequestParam and @PathVariable roles