When designing REST APIs in Spring Boot, developers typically rely on path variables (/users/{id}) or query parameters (?filter=active). But Spring also supports a lesser-known, powerful feature: Matrix Variables.
Matrix variables allow you to attach key–value pairs directly to URL path segments using ;. This gives you more expressive, resource-centric URLs when parameters logically belong to a specific resource path segment rather than the whole request.
In this blog, we’ll cover:
- What matrix variables are.
- Practical examples with Spring Boot
@MatrixVariable. - Whether configuration is needed.
- When to use path variables vs query parameters vs matrix variables.
What Are Matrix Variables?
Matrix variables are parameters embedded in path segments.
/products/101;filter=active;view=summary
products/101→ Path segmentfilter=activeandview=summary→ Matrix variables tied to101
Unlike query parameters, which apply to the entire request, matrix variables apply only to the path segment they are attached to.
Example 1: Product Details with Filter and View
@GetMapping("/products/{productId}")
public String getProductDetails(
@PathVariable Long productId,
// Extract a single matrix variable 'filter'
@MatrixVariable(name = "filter") String filter,
// Extract a single matrix variable 'view' with a default value
@MatrixVariable(name = "view", defaultValue = "full") String view) {
return String.format(
"Fetching product ID: %d, applying filter: '%s', with view style: '%s'",
productId, filter, view
);
}
Request URL:
GET /products/101;filter=active;view=summary
Response:
Fetching product ID: 101, applying filter: 'active', with view style: 'summary'
If view is omitted:
GET /products/101;filter=active
Response:
Fetching product ID: 101, applying filter: 'active', with view style: 'full'
Example 2: Reports with Multiple Matrix Variables
Matrix variables also support multiple values and can differ across path segments.
@GetMapping("/reports/{quarter}/format/{formatType}")
public String getQuarterlyReport(
@PathVariable String quarter,
@PathVariable String formatType,
// Capture all matrix variables for the 'quarter' path segment
@MatrixVariable(pathVar = "quarter") Map<String, String> quarterParams,
// Capture a specific multi-value variable from 'formatType'
@MatrixVariable(pathVar = "formatType", name = "options") List<String> formatOptions) {
return String.format(
"Generating %s report (Format: %s). Quarter Params: %s. Format Options: %s",
quarter, formatType, quarterParams, formatOptions
);
}
Request URL:
GET /reports/Q3;status=pending,approved/format/csv;options=compact;options=secure
Response:
Generating Q3 report (Format: csv). Quarter Params: {status=pending,approved}. Format Options: [compact, secure]
Key Takeaways
- Use Path Variables for resource identity.
- Use Query Parameters for global filtering and options.
- Use Matrix Variables for segment-specific parameters, especially when multiple path segments may each have their own metadata.
- No config is needed in Spring Boot 3.x, but required in 2.x and older.
Matrix variables are a hidden gem in Spring Boot. They provide a clean way to make URLs more expressive and resource-focused — especially when parameters naturally belong to specific path segments.
Next time you design an API, ask yourself:
- Does it identify the resource? → Path Variable
- Is it a global filter? → Query Parameter
- Is it tied to a specific path segment? → Matrix Variable
Designing with these distinctions will make your APIs more intuitive and RESTful.

