URL Query String Guide: Encode Parameters, Build Test Links, and Debug API Requests
urlsquery-stringsapi-testingencodingweb-development

URL Query String Guide: Encode Parameters, Build Test Links, and Debug API Requests

CClicky Editorial Team
2026-11-14
7 min read

Learn how to encode query parameters, handle spaces and plus signs, build API URLs, test repeated values, and debug what servers actually receive.

Query strings look simple, but a single unencoded ampersand, plus sign, or fragment marker can change what an application receives. This guide explains how to build API links, encode values safely, test repeated and Unicode parameters, and troubleshoot the difference between the URL you intended and the request your server actually parsed.

Overview

A query string is the portion of a URL after ? and before an optional # fragment. It commonly carries filters, search terms, pagination values, feature flags, campaign parameters, or API options.

https://example.com/products?category=books&page=2

In this example, category=books and page=2 are query string parameters. The ampersand separates parameters, while the equals sign separates each name from its value. A parameter can also appear without an equals sign, such as ?debug; how that is interpreted depends on the browser, framework, or server parser.

Encoding is needed when a value contains characters that have a structural meaning in a URL. For example, an ampersand inside a search term must be encoded so it is not mistaken for the start of another parameter.

Intended value: red & blue
Encoded value:  red%20%26%20blue

https://example.com/search?q=red%20%26%20blue

Use a URL encode decode online tool for quick inspection, but treat the result as a debugging aid rather than a substitute for understanding the receiving application. For repeatable work, build URLs with the URL and URLSearchParams APIs or the equivalent library in your server-side language.

URL parameter reference

Character or patternTypical meaningWhat to check
?Starts the query stringUse only one query delimiter; later question marks may be data or may be mishandled.
&Separates parametersEncode it as %26 when it belongs inside a value.
=Separates a name and valueEncode it inside a value when the receiving parser treats it structurally.
#Starts a browser fragmentFragments are normally not sent in the HTTP request; encode # as %23 when it is data.
+Literal plus in some contexts; space in form encodingConfirm whether the parser treats plus as a space before decoding.
SpaceNot normally written literallyUse percent encoding, commonly %20, or the serializer's documented form.
%Introduces a percent-encoded byteDo not double-encode an already encoded value unless that is intentional.

Checklist by scenario

Building a URL in JavaScript

Prefer structured APIs over manual string concatenation. They separate parameter names and values and handle percent encoding for you.

const url = new URL('https://api.example.com/items');
url.searchParams.set('q', 'red & blue');
url.searchParams.set('page', '2');

console.log(url.toString());
// https://api.example.com/items?q=red+%26+blue&page=2

The exact representation of spaces can vary between serializers. A plus sign in the output can represent a space under form-style query serialization. The important test is whether the server decodes the value as intended.

When a parameter can occur more than once, use append rather than set:

const url = new URL('https://api.example.com/items');
url.searchParams.append('tag', 'books');
url.searchParams.append('tag', 'fiction');

// tag=books&tag=fiction

Do not assume that every API understands arrays in the same way. Common conventions include repeated keys, comma-separated values, bracket notation such as tag[]=books, or JSON encoded as one value. Follow the API contract.

  1. List the required functional parameters separately from optional tracking parameters.
  2. Write down the intended decoded value for each parameter, including spaces, punctuation, and Unicode characters.
  3. Encode values individually; do not encode the entire URL after assembling it.
  4. Check that the destination path, query string, and fragment are in the correct order.
  5. Open the final link and verify both the visible result and the request captured in browser developer tools.

For campaign links, keep naming consistent. Decide whether names are lowercase, whether values use hyphens or underscores, and which parameters are required before a seasonal planning cycle begins. Do not place passwords, private keys, session tokens, or other sensitive data in a URL. URLs can appear in browser history, logs, copied links, referrer data, and analytics systems.

Testing an API request from the command line

Shell characters can be interpreted before the request reaches the HTTP client. Quote a complete URL when testing:

curl 'https://api.example.com/search?q=red%20%26%20blue&page=2'

For form-style request data, let the client encode individual fields when supported:

curl --get 'https://api.example.com/search' \
  --data-urlencode 'q=red & blue' \
  --data-urlencode 'page=2'

This approach reduces mistakes caused by spaces, ampersands, question marks, and shell expansion. For a broader request-debugging process, compare the request construction, payload, headers, and response using the REST API testing workflow.

Handling a search term, Unicode, or a literal plus sign

Test values that expose decoding differences:

  • red & blue
  • one+two
  • one two
  • 100%
  • café or another non-ASCII value
  • a=b&c=d
  • an empty value, such as q=
  • a missing value, such as q

A literal plus sign should be encoded as %2B when the server uses form-style decoding. Otherwise, it may become a space. Similarly, a percent sign should normally become %25 when it is part of the value.

What to double-check

Encoding happens at the value level

A common mistake is to encode a complete URL as though it were one value. That can turn delimiters such as ? and & into data and prevent the server from finding the intended parameters. Construct the URL from a trusted base, parameter names, and individually encoded values.

Decoding is not identical everywhere

Browser APIs, JavaScript serializers, backend frameworks, reverse proxies, command-line clients, and analytics systems may apply slightly different rules. In particular, compare how each layer handles spaces, plus signs, duplicate keys, empty values, malformed percent escapes, and Unicode.

Use a small test matrix rather than relying on one successful example:

Input valueExpected decoded valueObserved valuePass?
red & bluered & blueRecord server outputYes/No
one+twoone+twoRecord server outputYes/No
one twoone twoRecord server outputYes/No
cafécaféRecord server outputYes/No

Fragments are client-side navigation

Everything after # is generally handled by the browser and is not included in the HTTP request sent to the server. Therefore, /page?item=7#details sends item=7, but not details, to the server. If a server-side value contains a hash, encode it as %23.

Parameter order and duplicates may matter

Some applications preserve parameter order; others normalize or ignore it. Duplicate keys can be represented as a list, the first value, the last value, or an error. Test the behavior that your API contract requires. If you control the API, document whether repeated values are supported and how clients should send arrays.

Inspect the actual request

When a link behaves incorrectly, open browser developer tools, select the Network panel, reload the page, and inspect the request URL. Compare it with the value shown in the address bar and the value your code generated. On the server, log parsed parameter names and values carefully while avoiding credentials and personal data. If the request body is also involved, use a structured formatter and validator; the API payload debugging workflow covers related checks.

Common mistakes

  • Concatenating untrusted input: '?q=' + searchTerm can break when the term contains delimiters. Encode the value or use a URL builder.
  • Encoding twice: Turning %20 into %2520 usually means the percent sign was encoded a second time. Identify which layer owns encoding.
  • Decoding too early: Decoding a complete URL before parsing can turn data characters into delimiters. Parse the URL first and decode parameter values through the intended parser.
  • Assuming plus always means space: This depends on the serialization and parsing rules. Test a literal plus as %2B.
  • Putting a fragment before the query: In /page#section?x=1, ?x=1 is part of the fragment, not a query parameter. Use /page?x=1#section.
  • Using the wrong array convention: Repeated keys and comma-separated values are not automatically interchangeable.
  • Copying sensitive URLs into tickets or chats: Remove credentials, tokens, and private identifiers before sharing a request.
  • Checking only the browser display: A link can look correct while a redirect, proxy, router, or backend parser changes the request. Inspect each relevant hop.

For redirects and canonical URLs, also check whether parameters are preserved, removed, reordered, or accidentally appended more than once. Technical SEO teams can include these checks in a broader technical SEO content QA checklist.

When to revisit

Revisit your URL parameter checklist whenever the workflow or its inputs change. Useful checkpoints include:

  • before launching a seasonal campaign or changing tracking conventions;
  • when an API version, backend framework, router, proxy, or client library changes;
  • when adding a new parameter type, array format, redirect, or Unicode input;
  • when a bug report says that a search term, filter, or identifier arrived altered;
  • when moving requests from browser code to a command-line test, server job, or CI workflow;
  • when reviewing links that may expose private data or create duplicate crawlable URLs.

Keep a compact regression set with spaces, plus signs, ampersands, percent signs, Unicode, empty values, repeated keys, and fragments. Run it after relevant code or infrastructure changes, record the expected decoded values, and inspect both the outgoing request and the server-side result. When a tool or framework changes, confirm its current serialization behavior instead of relying on an old example. That small habit makes URL encode decode online tools, browser inspections, API tests, and production debugging much more reliable.

Related Topics

#urls#query-strings#api-testing#encoding#web-development
C

Clicky Editorial Team

Developer Tools Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.