Introduction

When Java code builds a URL with query parameters, the safe rule is simple: encode each parameter name and each parameter value, not the whole URL. The distinction matters because query separators such as ?, &, and = give the URL its structure and must stay readable to the server.

Encode the Parts That Carry Data

Query strings are not free-form text. They are structured as a base URL followed by name=value pairs separated by &. If you call URLEncoder on the entire URL string, Java will escape the separators too, and the server will no longer see a proper query string.

Use URLEncoder only on raw parameter names and values:

1import java.net.URLEncoder;
2import java.nio.charset.StandardCharsets;
3
4public class QueryEncodingDemo {
5    public static void main(String[] args) {
6        String baseUrl = "https://example.com/search";
7        String query = URLEncoder.encode("c++ basics", StandardCharsets.UTF_8);
8        String sort = URLEncoder.encode("updated desc", StandardCharsets.UTF_8);
9
10        String url = baseUrl + "?q=" + query + "&sort=" + sort;
11        System.out.println(url);
12    }
13}

That program prints a valid URL whose parameter values can safely contain spaces, plus signs, and other reserved characters.

Build Multiple Parameters with a Helper

Manual concatenation becomes fragile once a URL has optional parameters. A helper keeps the encoding rule in one place and avoids inconsistent handling across the codebase.

1import java.net.URLEncoder;
2import java.nio.charset.StandardCharsets;
3import java.util.LinkedHashMap;
4import java.util.Map;
5import java.util.stream.Collectors;
6
7public class UrlBuilder {
8    public static String toQueryString(Map<String, String> params) {
9        return params.entrySet().stream()
10            .map(entry ->
11                URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8) +
12                "=" +
13                URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8))
14            .collect(Collectors.joining("&"));
15    }
16
17    public static void main(String[] args) {
18        Map<String, String> params = new LinkedHashMap<>();
19        params.put("q", "A&B testing");
20        params.put("city", "München");
21        params.put("page", "1");
22
23        String url = "https://example.com/search?" + toQueryString(params);
24        System.out.println(url);
25    }
26}

Using LinkedHashMap preserves insertion order, which can be useful in logs or tests where deterministic output matters.

Understand + Versus %20

One detail surprises many developers: URLEncoder is form-oriented. It encodes spaces as +, not %20.

1import java.net.URLEncoder;
2import java.nio.charset.StandardCharsets;
3
4public class SpaceEncoding {
5    public static void main(String[] args) {
6        String encoded = URLEncoder.encode("hello world", StandardCharsets.UTF_8);
7        System.out.println(encoded); // hello+world
8    }
9}

For typical HTML form and query-string processing, that is correct. If an API explicitly requires %20, you may need a URI-building library or a post-processing replacement that is applied deliberately rather than by guesswork.

Query Encoding Is Not Path Encoding

Another common source of bugs is mixing path segments and query parameters. The path part of a URL follows different rules from the query string, and URLEncoder is not a general “make this safe for every part of a URL” tool.

If you are building something like https://example.com/files/report 2025.pdf?download=true, the path segment and the query value should not be treated as the same kind of data. The practical lesson is to encode based on URL component, not on the entire string.

Prefer a Higher-Level Client When Available

If your project already uses a library such as Spring's URI utilities, Apache HTTP components, or Java's newer HTTP APIs with URI builders around them, use those tools rather than hand-building every query string. They reduce duplication and make it harder to forget encoding on one parameter.

That said, knowing the low-level rule is still important because library abstractions are only safe when you understand what problem they solve.

Test with Realistic Input

Plain ASCII test data hides encoding problems. Include values with spaces, ampersands, slashes, question marks, and non-ASCII text in your tests. Bugs often appear only when user input contains characters that have a reserved meaning in URLs.

A quick sanity test can assert that the generated URL still contains the correct separators while the data-bearing pieces are escaped.

Common Pitfalls

The biggest mistake is encoding the whole URL in one operation. That breaks query structure and usually produces a URL the server cannot parse correctly.

Another mistake is assuming path and query values can be encoded the same way. They cannot. Encoding rules depend on the URL component.

Developers also get confused by the + encoding of spaces and think Java is wrong. In query-form encoding, that output is expected. The correct question is whether the receiving system also expects form-style decoding.

Summary

• In Java, encode each query parameter name and value separately.
• Do not pass the full URL string to URLEncoder.
• Expect URLEncoder to encode spaces as +.
• Keep query-string construction in a helper or URI builder when possible.
• Test with realistic input, especially special characters and non-ASCII text.