Query Parameters Guide: Structure, Encoding, and Best Practices

What Are Query Parameters?

Query parameters are the key-value pairs appended to a URL after the ? character. They pass data from the client to the server — search terms, filters, page numbers, and tracking codes all travel in query strings.

https://example.com/search?q=hello&lang=en&page=2
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                     query string

Each pair follows the format key=value, separated by &. The server reads these parameters to generate the right response.

Syntax Rules

A query string has strict formatting rules:

• Starts with ? after the path
• Contains key-value pairs: key=value
• Pairs separated by &
• Empty values are valid: key= (value is an empty string)
• Keys without = are valid: key (value is null or empty, depending on the parser)

?sort=price&order=asc&in_stock=
 ^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^
 key=value  key=value  key=(empty)

Encoding Rules

Not every character can appear raw in a query string. Reserved characters must be percent-encoded when used as data:

Space Encoding: %20 vs +

The treatment of spaces causes frequent confusion:

• %20 — standard percent-encoding per RFC 3986, valid everywhere in a URL
• + — shorthand from application/x-www-form-urlencoded, valid only in query strings

// JavaScript behavior
encodeURIComponent('hello world')  // "hello%20world" — always %20
new URLSearchParams({ q: 'hello world' }).toString()  // "q=hello+world" — uses +

When decoding, always use the right method for how the value was encoded. Mixing them produces incorrect results.

Double Encoding Trap

If you encode a value that is already encoded, you break the data:

// WRONG: double encoding
encodeURIComponent(encodeURIComponent('a&b'))
// "a%2526b" — the %26 got re-encoded to %2526

// CORRECT: encode once
encodeURIComponent('a&b')
// "a%26b"

Check whether data is already encoded before encoding it again.

Array Parameters

Passing arrays in query strings has no single standard. Three common patterns exist:

Which should you use?

• Repeated key — the most widely supported. Most server frameworks parse ?id=1&id=2 into an array automatically.
• Bracket notation — explicit but requires server-side support for [] parsing.
• Comma-separated — compact but forces you to split strings server-side. Does not work if values contain commas.

Pick one convention and document it in your API specification.

Pagination Patterns

Query parameters drive pagination in nearly every list API. Two main patterns dominate:

Offset-Based Pagination

GET /api/products?page=2&limit=20

Pros: Simple, allows jumping to any page.

Cons: Slow for large offsets (OFFSET 100000 scans 100K rows). Items may be skipped or duplicated if data changes between requests.

Cursor-Based Pagination

GET /api/products?cursor=abc123&limit=20

Pros: Consistent results even when data changes. Fast — no offset scanning.

Cons: No random page access. Requires the client to follow next_cursor links.

Use cursor-based pagination for large or frequently changing datasets. Use offset-based for small, static collections where page jumping matters.

REST API Parameter Conventions

Well-designed REST APIs follow consistent parameter naming:

Keep parameter names lowercase and use underscores for multi-word names: created_at, not createdAt. Consistency matters more than the specific convention — just pick one and stick to it.

Security Risks

Sensitive Data in URLs

Query parameters appear in browser history, server logs, referrer headers, and analytics tools. Never put secrets in a URL:

// DANGEROUS — exposes the token
GET /api/data?token=abc123secret

// SAFE — send via header
GET /api/data
Authorization: Bearer abc123secret

Sensitive values — API keys, passwords, session tokens — must travel in headers or request bodies, never in query strings.

Parameter Injection

Unvalidated query parameters can inject commands or manipulate backend logic:

// SQL injection via sort parameter
?sort=price; DROP TABLE products--

// NoSQL injection via filter
?filter[$gt]=

Always validate and sanitize query parameters server-side. Use allowlists for sort fields and filter keys. For more on URL-based attacks, see our URL Security Best Practices guide.

URL Length Limits

Browsers and servers impose URL length limits:

If your query string exceeds a few thousand characters, move data to the request body using POST.

Key Takeaways

• Query strings start with ? and contain key=value pairs separated by &
• Spaces can be %20 or +, but the two are not interchangeable — know which encoding your system uses
• Array parameters have three styles: repeated keys, brackets, and comma-separated
• Cursor-based pagination outperforms offset-based for large datasets
• REST APIs commonly use filter, sort, fields, and embed parameters
• Never place sensitive data in query strings — it leaks into logs and history
• Validate all query parameters server-side to prevent injection attacks

Related Guides

• URL Structure Explained
• URL Security Best Practices
• URL Encoding Guide

Try It Yourself

Parse and inspect query parameters instantly with our free URL Parser. Need to encode or decode parameter values? Try the URL Encoder/Decoder — it handles percent-encoding, plus signs, and special characters correctly in one click.