Comprehensive Guide to Sending URL Path Parameters and Query Parameters with RestTemplate

Problem Context and Common Error Analysis

In REST client development using the Spring Framework, RestTemplate is a widely adopted HTTP request utility. However, many developers encounter encoding issues when simultaneously employing path and query parameters. A typical erroneous scenario involves expecting to generate http://test.com/Services/rest/1234/Identifier?name=myName, but actually obtaining http://test.com/Services/rest/%7Bid%7D/Identifier?name=myName, where the path parameter {id} is not correctly substituted.

Core Solution: UriComponentsBuilder.buildAndExpand()

The UriComponentsBuilder class provided by Spring offers robust URI construction capabilities, with the buildAndExpand() method being pivotal for resolving such issues. This method enables:

• Automatic identification of path parameter placeholders (e.g., {id}) in the URI template
• Population of provided parameter values into corresponding positions
• Proper handling of query parameter appending
• Automatic URL encoding to ensure compliance

Complete Implementation Example

The following code demonstrates the correct implementation approach:

// Define base URL template containing path parameter placeholders
String urlTemplate = "http://test.com/solarSystem/planets/{planet}/moons/{moon}";

// Prepare path parameter mapping
Map<String, String> pathParams = new HashMap<>();
pathParams.put("planet", "Mars");
pathParams.put("moon", "Phobos");

// Construct URI components
UriComponentsBuilder builder = UriComponentsBuilder.fromUriString(urlTemplate)
    .queryParam("firstName", "Mark")
    .queryParam("lastName", "Watney");

// Generate complete URI
URI finalUri = builder.buildAndExpand(pathParams).toUri();

// Send request using RestTemplate
restTemplate.exchange(finalUri, HttpMethod.PUT, requestEntity, responseType);

In-Depth Technical Principle Analysis

The operational mechanism of the buildAndExpand() method is based on Spring's URI template engine:

1. Template Parsing Phase: Parses the URL string to identify placeholders in the {paramName} format
2. Parameter Mapping Phase: Matches provided Map parameters with placeholder names
3. Value Substitution Phase: Replaces all matched placeholders with actual parameter values
4. Encoding Processing Phase: Performs URL encoding on substituted values to ensure proper handling of special characters
5. Query Parameter Appending: Appends parameters added via queryParam() in the ?key=value&key2=value2 format

Comparative Analysis of Error Patterns

The issue with the original erroneous code lies in:

// Erroneous approach: Direct string construction without path parameter processing
String uriBuilder = builder.build().encode().toUriString();
restTemplate.exchange(uriBuilder, HttpMethod.PUT, requestEntity, class_p, params);

Defects of this approach:

• build().encode() only encodes the existing string without parameter substitution
• Path parameter placeholder {id} is encoded as %7Bid%7D instead of the actual value
• Additional params in the exchange method cannot correctly map to the already encoded URL

Best Practice Recommendations

Based on practical project experience, the following practices are recommended:

1. Unified Parameter Management: Consolidate all path parameters in a single Map for management
2. Chained Invocation Optimization: Utilize UriComponentsBuilder's fluent API to enhance code readability
3. Encoding Strategy Comprehension: Clearly understand the encoding timing differences between encode() and buildAndExpand()
4. Exception Handling: Add parameter validation to ensure all placeholders have corresponding parameter values
5. Performance Considerations: For high-frequency invocation scenarios, consider caching UriComponentsBuilder instances

Extended Application Scenarios

This method is applicable not only to basic REST calls but also extendable to:

• Internal communication between microservices
• Redirect URI construction in OAuth2 authorization flows
• Dynamic generation of file download links
• Automated appending of pagination query parameters
• URL localization processing for multilingual sites

By mastering the correct usage of UriComponentsBuilder, developers can construct complex REST API requests more flexibly and securely, avoid common URL encoding pitfalls, and enhance code robustness and maintainability.