Why URL parameter design matters
A well-designed URL is readable to humans, predictable for developers, and safe for servers. A poorly designed one gets misread, mistyped, and — in the worst case — exploited. Most web developers spend surprisingly little time thinking about query parameter design until a bug report comes in or a security audit flags something. This guide covers the principles that prevent both.
Use the Query String Builder to experiment with any of the patterns described here as you read.
Naming conventions
The single most controversial question in URL design is whether to use snake_case, camelCase, or kebab-case for parameter names. Here is what the major ecosystems actually do in practice.
snake_case (sort_by, page_size, created_after) is by far the most common in REST APIs. It reads naturally, avoids the percent-encoding that spaces require, and maps cleanly to Python and Ruby variable naming. GitHub, Stripe, and Twilio all use snake_case.
camelCase (sortBy, pageSize, createdAfter) appears in APIs built by teams with a JavaScript or Java background. It is perfectly valid but can feel odd in a URL context, and it requires consumers to remember capitalisation exactly.
kebab-case (sort-by, page-size) is common in HTML attribute names but rare in query parameters because hyphens look like minus signs and can confuse both humans and some parsers.
The golden rule: pick one style for your entire project and never mix them. A URL like /search?page_size=10&sortBy=name&created-after=2026-01-01 is a maintenance nightmare.
Required vs optional parameters
Structure your parameters so it is obvious which are mandatory and which are filters. A common pattern:
- Path parameters (
/users/123) for identifiers — things that uniquely locate a resource - Required query parameters for non-optional modifiers that change the query’s fundamental meaning
- Optional query parameters for pagination, sorting, filtering, formatting — things that have sensible defaults
Document the defaults explicitly. ?page=1&per_page=20 is better than leaving consumers to guess that the default page size is 20.
Pagination conventions
Three common pagination patterns, each with different trade-offs:
Offset pagination uses ?page=3&per_page=20 or ?offset=40&limit=20. Simple to implement and well-understood, but can return duplicate or skip items if rows are inserted or deleted between pages.
Cursor pagination uses ?cursor=eyJpZCI6MTIzfQ==&limit=20. A cursor (often a base64-encoded JSON object with the last-seen ID) gives stable pages even during mutations. More complex to implement but recommended for feeds that update frequently.
Keyset pagination uses ?after_id=123&limit=20. Simpler than cursor, requires a stable sort key. Twitter’s API uses this pattern.
Boolean parameters — the tricky ones
There are at least five ways to express a boolean in a URL:
?active=true/?active=false?active=1/?active=0?active=yes/?active=no- Presence/absence:
?active(presence = true, absence = false) ?active=on/?active=off(HTML form default for checkboxes)
Choose one representation and document it clearly. The presence/absence pattern is elegant but brittle — a client that sends ?active=false expecting false but whose server treats presence-of-key as true will have a hard-to-find bug.
Encoding: what to encode, what not to
A common mistake is over-encoding or under-encoding parameter values. The rules:
Always encode: spaces, &, =, #, +, %, and any non-ASCII character (including Unicode). These have special meaning in a URL or will be misinterpreted by parsers.
Never encode (the unreserved characters): A–Z, a–z, 0–9, -, _, ., ~. Encoding them is wasteful and technically incorrect per RFC 3986, though most parsers tolerate it.
The + trap: In a query string, + is sometimes treated as a space (form-urlencoded encoding). If your value legitimately contains a + (for example, a phone number like +91-98765-43210), encode it as %2B. Otherwise the server will decode it as a space. The Query String Builder handles this correctly for you.
Use the encodeURIComponent() function in JavaScript (or its equivalent in your language) to encode parameter values. Never use encodeURI() on a parameter value — it does not encode &, =, or +.
Arrays in query strings
There is no standard for passing arrays in a URL. Four common approaches:
# Repeated key (most common, supported by most frameworks)
?tag=javascript&tag=react&tag=css
# Bracket notation (PHP, Ruby on Rails)
?tag[]=javascript&tag[]=react
# Index bracket (some frameworks)
?tag[0]=javascript&tag[1]=react
# Comma-separated (simpler, but hard to parse if values contain commas)
?tag=javascript,react,cssUse repeated keys unless your server framework requires otherwise. The Query String Builder generates repeated-key arrays and warns you about duplicate keys so you can verify your intent.
Security considerations
Query parameters are part of the URL, which means they appear in:
- Browser history
- Server access logs
- Referrer headers sent to third-party scripts
- Browser DevTools Network panel
Never put sensitive data in query parameters: passwords, session tokens, credit card numbers, PII. Use POST bodies, HTTP headers, or short-lived tokens for anything sensitive.
Validate server-side always: A URL is user-controlled input. Parse parameter values strictly — reject unexpected characters, enforce length limits, and validate types. A parameter named limit should be validated as a positive integer, not used directly in a SQL query.
Watch out for open redirects: If your app has a ?redirect= or ?next= parameter, validate that the target URL is on your own domain before redirecting. Unvalidated redirects are a common phishing vector.
SEO implications of query parameters
Search engines handle query parameters differently depending on how you configure them:
Crawl budget: Every unique URL with a parameter combination counts against your crawl budget. For large e-commerce sites with hundreds of filter combinations, this can mean important pages get crawled less often.
Duplicate content: /products?color=blue and /products?colour=blue might return the same content, creating a duplicate content problem. Use canonical tags to tell search engines which URL is the primary one.
Parameter handling in Google Search Console: You can tell Google which parameters change content, which are irrelevant (tracking parameters), and which should not be crawled. Use this to prevent parameter variations from diluting your SEO.
UTM parameters are generally safe: Google treats UTM parameters (?utm_source=, ?utm_medium=, etc.) as tracking parameters and typically consolidates them. Use UTM Builder to add them consistently.
Common mistakes and how to avoid them
Forgetting to encode: Build query strings programmatically using URLSearchParams (JavaScript) or your framework’s equivalent — never by string concatenation.
Inconsistent naming: A mix of user_id, userId, and userid across your endpoints is a sign of organic growth without a style guide. Write down your convention and enforce it in code review.
Exposing internal identifiers: Using a database row ID as a URL parameter (?user_id=42) tells users about your data model and makes enumeration attacks trivial. Consider UUIDs or opaque tokens instead.
Not versioning: If you need to change parameter semantics, add a version prefix (?v=2&sort_by=name) or use a versioned path (/v2/products). Breaking changes to query parameters break existing integrations without warning.
Thoughtful query parameter design pays dividends every time someone integrates with your API or debugs a broken link. Build your next URL with the Query String Builder to make sure the encoding is right from the start.