URL Encoding Best Practices for Web Developers: Complete Guide

Original character → UTF-8 bytes → Percent encode each byte

Example: Space character
1. Character: " "
2. ASCII code: 32 (0x20 in hexadecimal)
3. Encoded: %20

Example: @ symbol
1. Character: "@"
2. ASCII code: 64 (0x40 in hexadecimal)
3. Encoded: %40

Example: emoji 🚀
1. Character: "🚀"
2. UTF-8 bytes: F0 9F 9A 80
3. Encoded: %F0%9F%9A%80

Character  | Encoded | Description
-----------|---------|---------------------------
Space      | %20     | Space (or + in form data)
!          | %21     | Exclamation mark
"          | %22     | Double quote
#          | %23     | Hash/pound sign
$          | %24     | Dollar sign
%          | %25     | Percent sign
&          | %26     | Ampersand
'          | %27     | Single quote/apostrophe
(          | %28     | Opening parenthesis
)          | %29     | Closing parenthesis
*          | %2A     | Asterisk
+          | %2B     | Plus sign
,          | %2C     | Comma
/          | %2F     | Forward slash
:          | %3A     | Colon
;          | %3B     | Semicolon
=          | %3D     | Equals sign
?          | %3F     | Question mark
@          | %40     | At sign
[          | %5B     | Opening bracket
]          | %5D     | Closing bracket

Character: "é" (e with acute accent)
UTF-8 bytes: C3 A9
URL encoded: %C3%A9

Character: "中" (Chinese character)
UTF-8 bytes: E4 B8 AD
URL encoded: %E4%B8%AD

Character: "🚀" (rocket emoji)
UTF-8 bytes: F0 9F 9A 80
URL encoded: %F0%9F%9A%80

Full example:
Original: "Hello 世界!"
Encoded:  "Hello%20%E4%B8%96%E7%95%8C!"

// ✅ CORRECT - Use for query parameter values
const searchQuery = "[email protected]";
const encoded = encodeURIComponent(searchQuery);
console.log(encoded); // user%40example.com

const url = `https://api.com/search?q=${encodeURIComponent(searchQuery)}`;
// Result: https://api.com/search?q=user%40example.com

// More examples
encodeURIComponent("Hello World");     // "Hello%20World"
encodeURIComponent("100% true");       // "100%25%20true"
encodeURIComponent("C++ developer");   // "C%2B%2B%20developer"
encodeURIComponent("[email protected]"); // "user%40domain.com"
encodeURIComponent("a&b=c");          // "a%26b%3Dc"

// Encodes these characters: ; , / ? : @ & = + $ #
// Plus spaces and all non-ASCII characters

// Use for encoding complete URLs
const baseUrl = "https://example.com/search";
const query = "Hello World";
const url = `${baseUrl}?q=${query}`;

const encoded = encodeURI(url);
console.log(encoded);
// https://example.com/search?q=Hello%20World

// encodeURI() preserves URL structure
encodeURI("https://example.com/path?q=test");
// https://example.com/path?q=test (unchanged)

encodeURI("https://example.com/Hello World");
// https://example.com/Hello%20World

// Does NOT encode: ; , / ? : @ & = + $ #
// These are valid URL characters

// ❌ DEPRECATED - Do not use!
const text = "Hello World";
const encoded = escape(text);
// "Hello%20World"

// Problems with escape():
// 1. Non-standard (not in any specification)
// 2. Doesn't properly encode non-ASCII characters
// 3. Uses different encoding for some characters
// 4. Not compatible with modern web standards

// Example of issues:
escape("€");  // "%u20AC" - wrong format!
escape("世界"); // "%u4E16%u754C" - wrong format!

// ✅ Use encodeURIComponent() instead
encodeURIComponent("€");  // "%E2%82%AC" - correct!
encodeURIComponent("世界"); // "%E4%B8%96%E7%95%8C" - correct!

// Comparison of encoding functions

const url = "https://example.com/path?q=hello world&lang=en";

// encodeURI() - Encodes spaces but preserves URL structure
console.log(encodeURI(url));
// https://example.com/path?q=hello%20world&lang=en

// encodeURIComponent() - Encodes everything including URL chars
console.log(encodeURIComponent(url));
// https%3A%2F%2Fexample.com%2Fpath%3Fq%3Dhello%20world%26lang%3Den

// When to use each:

// ✅ Use encodeURIComponent() for:
const param = "[email protected]";
`https://api.com/search?email=${encodeURIComponent(param)}`

// ✅ Use encodeURI() for:
const fullUrl = "https://example.com/Hello World.html";
encodeURI(fullUrl)

// Rule of thumb:
// - Parameter values: encodeURIComponent()
// - Complete URLs: encodeURI()
// - Nothing else: never use escape()

// Decoding URL-encoded strings

// decodeURIComponent() - Most common
const encoded = "user%40example.com";
const decoded = decodeURIComponent(encoded);
console.log(decoded); // [email protected]

// decodeURI() - For complete URLs
const encodedUrl = "https://example.com/Hello%20World";
const decodedUrl = decodeURI(encodedUrl);
console.log(decodedUrl); // https://example.com/Hello World

// More examples
decodeURIComponent("Hello%20World");     // "Hello World"
decodeURIComponent("100%25%20true");     // "100% true"
decodeURIComponent("C%2B%2B");           // "C++"
decodeURIComponent("%E4%B8%96%E7%95%8C"); // "世界"
decodeURIComponent("%F0%9F%9A%80");      // "🚀"

// Handle errors gracefully
function safeDecode(str) {
  try {
    return decodeURIComponent(str);
  } catch (e) {
    console.error('Invalid URL encoding:', str);
    return str; // Return original if decoding fails
  }
}

from urllib.parse import quote, unquote, urlencode, parse_qs

# Encode single value (like encodeURIComponent)
text = "[email protected]"
encoded = quote(text)
print(encoded)  # user%40example.com

# Decode
decoded = unquote(encoded)
print(decoded)  # [email protected]

# Encode query parameters
params = {
    'q': 'Hello World',
    'lang': 'en',
    'sort': 'date'
}
query_string = urlencode(params)
print(query_string)  # q=Hello+World&lang=en&sort=date

# Parse query string
parsed = parse_qs('q=Hello+World&lang=en')
print(parsed)  # {'q': ['Hello World'], 'lang': ['en']}

# Safe characters (don't encode)
encoded = quote('Hello World', safe='')
print(encoded)  # Hello%20World

# With safe characters
encoded = quote('https://example.com', safe=':/')
print(encoded)  # https://example.com

<?php
// Encode (like encodeURIComponent)
$text = "[email protected]";
$encoded = rawurlencode($text);
echo $encoded; // user%40example.com

// Decode
$decoded = rawurldecode($encoded);
echo $decoded; // [email protected]

// urlencode() - Encodes spaces as +
$space = urlencode("Hello World");
echo $space; // Hello+World

// rawurlencode() - Encodes spaces as %20 (preferred)
$space = rawurlencode("Hello World");
echo $space; // Hello%20World

// Build query string
$params = [
    'q' => 'Hello World',
    'lang' => 'en',
    'user' => '[email protected]'
];
$query = http_build_query($params);
echo $query; // q=Hello+World&lang=en&user=user%40example.com

// Parse query string
parse_str($query, $parsed);
print_r($parsed);
// Array ( [q] => Hello World [lang] => en [user] => [email protected] )
?>

import java.net.URLEncoder;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;

public class URLEncodingExample {
    public static void main(String[] args) {
        // Encode
        String text = "[email protected]";
        String encoded = URLEncoder.encode(text, StandardCharsets.UTF_8);
        System.out.println(encoded); // user%40example.com

        // Decode
        String decoded = URLDecoder.decode(encoded, StandardCharsets.UTF_8);
        System.out.println(decoded); // [email protected]

        // Build query string
        String query = String.format(
            "q=%s&lang=%s",
            URLEncoder.encode("Hello World", StandardCharsets.UTF_8),
            URLEncoder.encode("en", StandardCharsets.UTF_8)
        );
        System.out.println(query); // q=Hello+World&lang=en

        // Note: Java uses + for spaces in form encoding
        // Use replace if you need %20 instead
        String withPercent = encoded.replace("+", "%20");
    }
}

using System;
using System.Web;
using System.Net;

class Program
{
    static void Main()
    {
        // Encode (like encodeURIComponent)
        string text = "[email protected]";
        string encoded = Uri.EscapeDataString(text);
        Console.WriteLine(encoded); // user%40example.com

        // Decode
        string decoded = Uri.UnescapeDataString(encoded);
        Console.WriteLine(decoded); // [email protected]

        // Alternative: WebUtility
        string encoded2 = WebUtility.UrlEncode("Hello World");
        Console.WriteLine(encoded2); // Hello+World

        string decoded2 = WebUtility.UrlDecode(encoded2);
        Console.WriteLine(decoded2); // Hello World

        // Build query string
        var builder = new UriBuilder("https://api.com");
        builder.Query = $"q={Uri.EscapeDataString("Hello World")}&lang=en";
        Console.WriteLine(builder.Uri);
        // https://api.com/?q=Hello%20World&lang=en
    }
}

require 'uri'
require 'cgi'

# Encode
text = "[email protected]"
encoded = URI.encode_www_form_component(text)
puts encoded  # user%40example.com

# Decode
decoded = URI.decode_www_form_component(encoded)
puts decoded  # [email protected]

# Build query string
params = { q: "Hello World", lang: "en" }
query = URI.encode_www_form(params)
puts query  # q=Hello+World&lang=en

# Parse query string
parsed = URI.decode_www_form(query)
puts parsed.inspect
# [["q", "Hello World"], ["lang", "en"]]

# CGI module (alternative)
encoded = CGI.escape("Hello World")
puts encoded  # Hello+World

decoded = CGI.unescape(encoded)
puts decoded  # Hello World

package main

import (
    "fmt"
    "net/url"
)

func main() {
    // Encode value
    text := "[email protected]"
    encoded := url.QueryEscape(text)
    fmt.Println(encoded) // user%40example.com

    // Decode value
    decoded, _ := url.QueryUnescape(encoded)
    fmt.Println(decoded) // [email protected]

    // Build query string
    params := url.Values{}
    params.Add("q", "Hello World")
    params.Add("lang", "en")
    query := params.Encode()
    fmt.Println(query) // lang=en&q=Hello+World

    // Parse URL
    u, _ := url.Parse("https://api.com/search?q=Hello+World")
    fmt.Println(u.Query().Get("q")) // Hello World

    // Encode path segment
    path := url.PathEscape("Hello World.html")
    fmt.Println(path) // Hello%20World.html
}

// Spaces in query parameters

// ❌ WRONG - Space breaks URL
const query = "Hello World";
const url = `https://api.com/search?q=${query}`;
// Result: https://api.com/search?q=Hello World
// Browser treats this as: q=Hello and unknown "World" parameter

// ✅ CORRECT - Encode the space
const encoded = encodeURIComponent(query);
const correctUrl = `https://api.com/search?q=${encoded}`;
// Result: https://api.com/search?q=Hello%20World

// Server receives: "Hello World" ✓

// Search query with special characters
const searchTerm = "What is C++?";

// ❌ WRONG
const badUrl = `/search?q=${searchTerm}`;
// /search?q=What is C++?
// ? and + will break the URL

// ✅ CORRECT
const goodUrl = `/search?q=${encodeURIComponent(searchTerm)}`;
// /search?q=What%20is%20C%2B%2B%3F

// More examples
const searches = [
    "100% coverage",
    "Rock & Roll",
    "AT&T",
    "[email protected]",
    "path/to/file"
];

searches.forEach(term => {
    console.log(`/search?q=${encodeURIComponent(term)}`);
});
// /search?q=100%25%20coverage
// /search?q=Rock%20%26%20Roll
// /search?q=AT%26T
// /search?q=user%40example.com
// /search?q=path%2Fto%2Ffile

// Email addresses in URLs
const email = "[email protected]";

// ❌ WRONG - + has special meaning (space)
const badUrl = `/api/users?email=${email}`;
// Server receives: "user [email protected]" (wrong!)

// ✅ CORRECT
const goodUrl = `/api/users?email=${encodeURIComponent(email)}`;
// /api/users?email=user%2Btag%40example.com
// Server receives: "[email protected]" ✓

// Verification emails
const verifyUrl = `https://example.com/verify?email=${encodeURIComponent(email)}&token=abc123`;

// Multiple query parameters
function buildUrl(baseUrl, params) {
    const queryParts = [];

    for (const [key, value] of Object.entries(params)) {
        const encodedKey = encodeURIComponent(key);
        const encodedValue = encodeURIComponent(value);
        queryParts.push(`${encodedKey}=${encodedValue}`);
    }

    return `${baseUrl}?${queryParts.join('&')}`;
}

// Usage
const url = buildUrl('https://api.com/search', {
    q: 'Hello World',
    lang: 'en',
    sort: 'date',
    filter: 'type:article',
    user: '[email protected]'
});

console.log(url);
// https://api.com/search?q=Hello%20World&lang=en&sort=date&filter=type%3Aarticle&user=user%40example.com

// URL as a parameter (redirect URL)
const returnUrl = "https://example.com/dashboard?tab=settings&view=profile";

// ❌ WRONG - URL structure gets mangled
const badUrl = `https://auth.com/login?return=${returnUrl}`;
// https://auth.com/login?return=https://example.com/dashboard?tab=settings&view=profile
// Browser thinks tab and view are parameters of auth.com!

// ✅ CORRECT - Encode the entire URL
const goodUrl = `https://auth.com/login?return=${encodeURIComponent(returnUrl)}`;
// https://auth.com/login?return=https%3A%2F%2Fexample.com%2Fdashboard%3Ftab%3Dsettings%26view%3Dprofile

// On server, decode to get original URL
const params = new URLSearchParams(window.location.search);
const originalUrl = params.get('return');
// "https://example.com/dashboard?tab=settings&view=profile" ✓

// Form submission
const form = document.querySelector('form');

form.addEventListener('submit', (e) => {
    e.preventDefault();

    const formData = new FormData(form);
    const params = new URLSearchParams();

    // Add form data to URL parameters
    for (const [key, value] of formData) {
        params.append(key, value);
    }

    const url = `/api/submit?${params.toString()}`;
    // URLSearchParams automatically encodes values

    fetch(url, { method: 'GET' })
        .then(response => response.json())
        .then(data => console.log(data));
});

// Manual encoding
const formData = {
    name: "John O'Brien",
    comment: "Great product! 5/5 stars ⭐",
    email: "[email protected]"
};

const queryString = Object.entries(formData)
    .map(([key, val]) => `${encodeURIComponent(key)}=${encodeURIComponent(val)}`)
    .join('&');

console.log(queryString);
// name=John%20O'Brien&comment=Great%20product!%205%2F5%20stars%20%E2%AD%90&email=john%2Bnewsletter%40example.com

// API request with encoded parameters
async function searchAPI(query, filters) {
    const params = new URLSearchParams({
        q: query,
        category: filters.category,
        minPrice: filters.minPrice,
        maxPrice: filters.maxPrice,
        tags: filters.tags.join(',')
    });

    const url = `https://api.example.com/products?${params}`;

    const response = await fetch(url);
    return response.json();
}

// Usage
const results = await searchAPI('laptop computer', {
    category: 'Electronics & Computers',
    minPrice: 500,
    maxPrice: 2000,
    tags: ['SSD', '16GB RAM', 'i7']
});

// Generated URL:
// https://api.example.com/products?q=laptop+computer&category=Electronics+%26+Computers&minPrice=500&maxPrice=2000&tags=SSD%2C16GB+RAM%2Ci7

// ❌ WRONG - Double encoding
const email = "[email protected]";
const encoded = encodeURIComponent(email);
const doubleEncoded = encodeURIComponent(encoded);

console.log(email);          // [email protected]
console.log(encoded);        // user%40example.com
console.log(doubleEncoded);  // user%2540example.com (WRONG!)

// Server receives: "user%40example.com" instead of "[email protected]"

// ✅ CORRECT - Encode only once
const url = `/api?email=${encodeURIComponent(email)}`;

// Common mistake: Encoding already-encoded strings
function buildUrl(baseUrl, params) {
    // If params are already encoded, don't encode again!
    return `${baseUrl}?${params}`; // params already encoded
}

// ❌ WRONG - Using encodeURI() for parameter value
const email = "[email protected]";
const wrongUrl = `/api?email=${encodeURI(email)}`;
// /[email protected]
// @ is NOT encoded by encodeURI() - wrong!

// ✅ CORRECT - Use encodeURIComponent() for parameter values
const correctUrl = `/api?email=${encodeURIComponent(email)}`;
// /api?email=user%40example.com ✓

// Wrong:
encodeURI("name=John&age=30");
// "name=John&age=30" - & and = not encoded!

// Correct:
encodeURIComponent("name=John&age=30");
// "name%3DJohn%26age%3D30" - properly encoded ✓

// ❌ WRONG - No encoding
const search = "What is C++?";
fetch(`/search?q=${search}`);
// URL: /search?q=What is C++?
// Browser interprets ? as new parameter separator!

// ✅ CORRECT - Always encode
fetch(`/search?q=${encodeURIComponent(search)}`);
// URL: /search?q=What%20is%20C%2B%2B%3F ✓

// Real-world bug example:
// User searches for "R&D department"
const badSearch = `/search?q=R&D department`;
// Browser sees: q=R and unknown parameter "D"
// Server receives q="R" (wrong!)

const goodSearch = `/search?q=${encodeURIComponent("R&D department")}`;
// /search?q=R%26D%20department
// Server receives q="R&D department" ✓

// ❌ WRONG - Encoding the entire URL
const url = "https://example.com/search?q=test&lang=en";
const wrong = encodeURIComponent(url);
// "https%3A%2F%2Fexample.com%2Fsearch%3Fq%3Dtest%26lang%3Den"
// This is not a valid URL!

// ✅ CORRECT - Encode only the values
const baseUrl = "https://example.com/search";
const params = {
    q: "test",
    lang: "en"
};

const correct = baseUrl + '?' + Object.entries(params)
    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
    .join('&');
// "https://example.com/search?q=test&lang=en" ✓

// Or use URL API
const url = new URL('https://example.com/search');
url.searchParams.append('q', 'test');
url.searchParams.append('lang', 'en');
console.log(url.href);

// Server receives encoded parameter
// URL: /api/user?name=John%20Doe

// ❌ WRONG - Using encoded value directly
const params = new URLSearchParams(window.location.search);
const name = params.get('name');
console.log(name); // "John Doe" ✓ (URLSearchParams auto-decodes)

// But if parsing manually:
const query = window.location.search; // "?name=John%20Doe"
const nameEncoded = query.split('=')[1]; // "John%20Doe"
console.log(nameEncoded); // Still encoded! (WRONG)

// ✅ CORRECT - Decode manually parsed values
const nameDecoded = decodeURIComponent(nameEncoded);
console.log(nameDecoded); // "John Doe" ✓

// Always decode before using:
function getQueryParam(name) {
    const value = new URLSearchParams(window.location.search).get(name);
    return value; // Already decoded by URLSearchParams
}

// URL paths vs query parameters

// ❌ WRONG - Encoding path separators
const path = "/api/users/123";
const wrong = encodeURIComponent(path);
// "%2Fapi%2Fusers%2F123" - slashes encoded (wrong for paths!)

// ✅ CORRECT - Don't encode path structure
// Paths are part of URL structure, not data

// If you have filename in path:
const filename = "report 2024.pdf";
const correctPath = `/files/${encodeURIComponent(filename)}`;
// "/files/report%202024.pdf" ✓

// For complex path segments, encode each segment:
function buildPath(...segments) {
    return '/' + segments
        .map(segment => encodeURIComponent(segment))
        .join('/');
}

const path = buildPath('users', '[email protected]', 'profile');
// "/users/john%40example.com/profile" ✓

// Handle edge cases

// Empty strings
const empty = encodeURIComponent("");
console.log(empty); // "" (empty string is valid)

// Null and undefined
const nullValue = encodeURIComponent(null);
console.log(nullValue); // "null" (converts to string!)

// ✅ Better: Check before encoding
function encodeParam(value) {
    if (value == null) return '';
    return encodeURIComponent(String(value));
}

// Arrays
const tags = ['javascript', 'web dev', 'tutorial'];

// Option 1: Join then encode
const joined = encodeURIComponent(tags.join(','));
// "javascript%2Cweb%20dev%2Ctutorial"

// Option 2: Multiple same-named parameters
const params = tags.map(tag => `tags=${encodeURIComponent(tag)}`).join('&');
// "tags=javascript&tags=web%20dev&tags=tutorial"

// Option 3: URLSearchParams
const searchParams = new URLSearchParams();
tags.forEach(tag => searchParams.append('tags', tag));
// "tags=javascript&tags=web+dev&tags=tutorial"

// Safe query string builder
function buildQueryString(params) {
    const parts = [];

    for (const [key, value] of Object.entries(params)) {
        // Skip null/undefined
        if (value == null) continue;

        // Handle arrays
        if (Array.isArray(value)) {
            value.forEach(item => {
                parts.push(
                    `${encodeURIComponent(key)}=${encodeURIComponent(item)}`
                );
            });
        } else {
            parts.push(
                `${encodeURIComponent(key)}=${encodeURIComponent(value)}`
            );
        }
    }

    return parts.join('&');
}

// Usage
const query = buildQueryString({
    search: 'Hello World',
    category: 'Books & Media',
    tags: ['fiction', 'bestseller'],
    minPrice: 10,
    inStock: true,
    discount: null // Will be skipped
});

console.log(query);
// search=Hello%20World&category=Books%20%26%20Media&tags=fiction&tags=bestseller&minPrice=10&inStock=true

// Parse URL safely
const url = "https://api.com/search?q=Hello%20World&lang=en&tags=js&tags=web";

// Modern approach: URL and URLSearchParams
const urlObj = new URL(url);

console.log(urlObj.protocol);  // "https:"
console.log(urlObj.hostname);  // "api.com"
console.log(urlObj.pathname);  // "/search"

// Get single parameter
console.log(urlObj.searchParams.get('q'));    // "Hello World"
console.log(urlObj.searchParams.get('lang')); // "en"

// Get array parameter
console.log(urlObj.searchParams.getAll('tags')); // ["js", "web"]

// Iterate all parameters
for (const [key, value] of urlObj.searchParams) {
    console.log(`${key}: ${value}`);
}
// q: Hello World
// lang: en
// tags: js
// tags: web

// Convert to object
const params = Object.fromEntries(urlObj.searchParams);
console.log(params); // { q: "Hello World", lang: "en", tags: "web" }
// Note: Only gets last value for duplicate keys

// Get all as object with arrays
function getAllParams(searchParams) {
    const result = {};
    for (const [key, value] of searchParams) {
        if (key in result) {
            if (Array.isArray(result[key])) {
                result[key].push(value);
            } else {
                result[key] = [result[key], value];
            }
        } else {
            result[key] = value;
        }
    }
    return result;
}

// Validate decoded values
function getValidatedParam(name, validator) {
    const params = new URLSearchParams(window.location.search);
    const value = params.get(name);

    if (value === null) {
        return null;
    }

    // Validate decoded value
    if (validator && !validator(value)) {
        throw new Error(`Invalid parameter: ${name}`);
    }

    return value;
}

// Validators
const validators = {
    email: (val) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val),
    number: (val) => !isNaN(val) && val.trim() !== '',
    alphanumeric: (val) => /^[a-zA-Z0-9]+$/.test(val),
    url: (val) => {
        try { new URL(val); return true; }
        catch { return false; }
    }
};

// Usage
try {
    const email = getValidatedParam('email', validators.email);
    const age = getValidatedParam('age', validators.number);

    console.log('Valid params:', { email, age });
} catch (error) {
    console.error('Validation failed:', error.message);
}

// Sanitize for security
function sanitizeParam(value) {
    // Remove potentially dangerous characters
    return value
        .replace(/[<>"']/g, '')  // Remove HTML chars
        .replace(/javascript:/gi, '') // Remove JS protocol
        .trim();
}

// Modern URLSearchParams API

// Create from object
const params = new URLSearchParams({
    q: 'Hello World',
    lang: 'en',
    sort: 'date'
});

console.log(params.toString());
// "q=Hello+World&lang=en&sort=date"

// Add parameters
params.append('filter', 'active');
params.append('filter', 'verified'); // Multiple values

// Get parameters
console.log(params.get('q'));          // "Hello World"
console.log(params.getAll('filter')); // ["active", "verified"]

// Check existence
console.log(params.has('lang')); // true

// Update parameter
params.set('lang', 'es'); // Replaces existing value

// Delete parameter
params.delete('sort');

// Iterate
for (const [key, value] of params) {
    console.log(`${key} = ${value}`);
}

// Use with fetch
fetch('https://api.com/search?' + params.toString())
    .then(response => response.json());

// Parse from URL
const urlParams = new URLSearchParams(window.location.search);
const searchTerm = urlParams.get('q');

// Convert to object
const obj = Object.fromEntries(params);
console.log(obj); // { q: "Hello World", lang: "es", filter: "verified" }

// ❌ VULNERABLE - URL parameter injection
app.get('/redirect', (req, res) => {
    const url = req.query.url;
    res.redirect(url); // Dangerous!
});

// Attacker uses:
// /redirect?url=javascript:alert(document.cookie)
// /redirect?url=data:text/html,<script>steal()</script>

// ✅ SECURE - Validate redirect URLs
app.get('/redirect', (req, res) => {
    const url = req.query.url;

    // Whitelist allowed domains
    const allowed = ['example.com', 'trusted.com'];

    try {
        const parsed = new URL(url);

        // Check protocol
        if (!['http:', 'https:'].includes(parsed.protocol)) {
            return res.status(400).send('Invalid protocol');
        }

        // Check domain
        if (!allowed.includes(parsed.hostname)) {
            return res.status(400).send('Domain not allowed');
        }

        res.redirect(url);
    } catch (e) {
        res.status(400).send('Invalid URL');
    }
});

// Open redirect vulnerability

// ❌ VULNERABLE
app.get('/login', (req, res) => {
    const returnUrl = req.query.return;
    // After login, redirect to returnUrl
    res.redirect(returnUrl); // Attacker can redirect anywhere!
});

// Attacker creates phishing link:
// https://yoursite.com/login?return=https://evil.com

// ✅ SECURE - Validate redirect URLs
function isValidReturnUrl(url) {
    try {
        const parsed = new URL(url);

        // Only allow same origin
        return parsed.origin === 'https://yoursite.com';
    } catch {
        return false;
    }
}

app.get('/login', (req, res) => {
    const returnUrl = req.query.return || '/dashboard';

    if (!isValidReturnUrl(returnUrl)) {
        return res.status(400).send('Invalid return URL');
    }

    // Proceed with login...
    res.redirect(returnUrl);
});

// Alternative: Use relative paths only
function isRelativePath(url) {
    return url.startsWith('/') && !url.startsWith('//');
}

// XSS through URL parameters

// ❌ VULNERABLE - Displaying unescaped URL parameter
app.get('/search', (req, res) => {
    const query = req.query.q;
    res.send(`<h1>Results for: ${query}</h1>`);
});

// Attacker uses:
// /search?q=<script>alert(document.cookie)</script>

// ✅ SECURE - Escape output
const escapeHtml = (str) => {
    return str
        .replace(/&/g, '&amp;')
        .replace(/</g, '&lt;')
        .replace(/>/g, '&gt;')
        .replace(/"/g, '&quot;')
        .replace(/'/g, '&#039;');
};

app.get('/search', (req, res) => {
    const query = escapeHtml(req.query.q || '');
    res.send(`<h1>Results for: ${query}</h1>`);
});

// Better: Use templating engine with auto-escaping
app.get('/search', (req, res) => {
    res.render('search', {
        query: req.query.q // Template engine escapes automatically
    });
});

// SQL injection via URL parameters

// ❌ VULNERABLE - String concatenation
app.get('/users', (req, res) => {
    const name = req.query.name;
    const query = `SELECT * FROM users WHERE name = '${name}'`;
    db.query(query); // Dangerous!
});

// Attacker uses:
// /users?name=admin' OR '1'='1

// ✅ SECURE - Parameterized queries
app.get('/users', (req, res) => {
    const name = req.query.name;

    // Use parameterized query
    const query = 'SELECT * FROM users WHERE name = ?';
    db.query(query, [name], (err, results) => {
        if (err) return res.status(500).send('Error');
        res.json(results);
    });
});

// Additional validation
function validateUsername(username) {
    // Only alphanumeric and underscore
    return /^[a-zA-Z0-9_]+$/.test(username);
}

app.get('/users', (req, res) => {
    const name = req.query.name;

    if (!validateUsername(name)) {
        return res.status(400).send('Invalid username');
    }

    const query = 'SELECT * FROM users WHERE name = ?';
    db.query(query, [name], (err, results) => {
        if (err) return res.status(500).send('Error');
        res.json(results);
    });
});

const text = "Hello <World> & Friends!";

// URL Encoding
const urlEncoded = encodeURIComponent(text);
console.log(urlEncoded);
// "Hello%20%3CWorld%3E%20%26%20Friends!"

// HTML Encoding
function htmlEncode(str) {
    return str
        .replace(/&/g, '&amp;')
        .replace(/</g, '&lt;')
        .replace(/>/g, '&gt;');
}
const htmlEncoded = htmlEncode(text);
console.log(htmlEncoded);
// "Hello &lt;World&gt; &amp; Friends!"

// When to use:
// URL Encoding: Query parameters, URL paths
// HTML Encoding: Displaying text in HTML

// Example:
const userInput = "<script>alert('xss')</script>";

// In URL:
const url = `/search?q=${encodeURIComponent(userInput)}`;

// In HTML:
const html = `<p>Search: ${htmlEncode(userInput)}</p>`;

const data = "[email protected]:password";

// URL Encoding
const urlEncoded = encodeURIComponent(data);
console.log(urlEncoded);
// "user%40example.com%3Apassword"

// Base64 Encoding
const base64Encoded = btoa(data);
console.log(base64Encoded);
// "dXNlckBleGFtcGxlLmNvbTpwYXNzd29yZA=="

// URL-safe Base64
const urlSafeBase64 = base64Encoded
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
console.log(urlSafeBase64);
// "dXNlckBleGFtcGxlLmNvbTpwYXNzd29yZA"

// When to use:
// URL Encoding: Human-readable data in URLs
// Base64: Binary data, tokens, credentials
// URL-safe Base64: Base64 data in URLs (JWT, tokens)

const data = { name: "John", age: 30, email: "[email protected]" };

// URL Encoding (query string)
const urlEncoded = new URLSearchParams(data).toString();
console.log(urlEncoded);
// "name=John&age=30&email=john%40example.com"

// JSON Encoding
const jsonEncoded = JSON.stringify(data);
console.log(jsonEncoded);
// '{"name":"John","age":30,"email":"[email protected]"}'

// JSON in URL (double encoding)
const jsonInUrl = encodeURIComponent(jsonEncoded);
console.log(jsonInUrl);
// "%7B%22name%22%3A%22John%22%2C%22age%22%3A30%2C%22email%22%3A%22john%40example.com%22%7D"

// When to use:
// URL query string: Simple key-value pairs, GET requests
// JSON: Complex nested data, POST/PUT requests
// JSON in URL: Passing structured data in URL (not recommended for large data)

// Better approach for complex data:
// Use POST with JSON body instead of URL parameters

// Internationalized Resource Identifiers (IRIs)
// IRIs allow Unicode characters in URLs

// Original IRI (with Unicode)
const iri = "https://example.com/中文/файл.html";

// Convert to ASCII URL (percent-encoded)
const url = encodeURI(iri);
console.log(url);
// "https://example.com/%E4%B8%AD%E6%96%87/%D1%84%D0%B0%D0%B9%D0%BB.html"

// Browser display vs actual URL:
// Display: https://example.com/中文/файл.html (IRI)
// Actual:  https://example.com/%E4%B8%AD%E6%96%87/%D1%84%D0%B0%D0%B9%D0%BB.html (URL)

// Modern browsers handle IRIs automatically
const link = document.createElement('a');
link.href = "https://example.com/中文";
console.log(link.href);
// Browser automatically encodes to valid URL

// Plus sign (+) has special meaning in form data

// In query strings, + means space (legacy HTML form encoding)
const query = "?search=hello+world";
const params = new URLSearchParams(query);
console.log(params.get('search')); // "hello world"

// But literal + must be encoded
const text = "C++ developer";

// Wrong: Using + for space
console.log("search=" + text.replace(/ /g, '+'));
// "search=C+++developer" (ambiguous!)

// Correct: Encode properly
console.log("search=" + encodeURIComponent(text));
// "search=C%2B%2B%20developer" (clear: C++ developer)

// URLSearchParams uses + for spaces (form encoding style)
const params = new URLSearchParams({ q: "hello world" });
console.log(params.toString()); // "q=hello+world"

// encodeURIComponent uses %20 for spaces (RFC 3986 style)
console.log(encodeURIComponent("hello world")); // "hello%20world"

// Both are valid and equivalent
// Decoders handle both correctly

// Fragment identifiers (hash)
// The part after # in URLs

const url = "https://example.com/page#section";

// Fragment is NOT sent to server
// It's processed by the browser only

// Encoding fragments
const fragment = "My Section & Notes";
const encodedFragment = encodeURIComponent(fragment);
const fullUrl = `https://example.com/page#${encodedFragment}`;
console.log(fullUrl);
// "https://example.com/page#My%20Section%20%26%20Notes"

// Reading fragments
const hash = window.location.hash; // "#My%20Section%20%26%20Notes"
const decoded = decodeURIComponent(hash.substring(1));
console.log(decoded); // "My Section & Notes"

// Updating fragments (doesn't reload page)
window.location.hash = encodeURIComponent("New Section");

// SPA routing often uses fragments
// Before: https://app.com/#/users/123
// Modern (history API): https://app.com/users/123

// Custom encoding function for specific needs

// Encode for filename (remove/replace unsafe chars)
function encodeFilename(filename) {
    return filename
        .replace(/[<>:"/\\|?*]/g, '_') // Replace unsafe chars
        .replace(/\s+/g, '_')            // Replace spaces
        .substring(0, 255);              // Limit length
}

console.log(encodeFilename("My Document: Final (v2).txt"));
// "My_Document__Final_(v2).txt"

// Encode for SQL LIKE pattern
function encodeLikePattern(pattern) {
    return pattern
        .replace(/\\/g, '\\\\')  // Escape backslash
        .replace(/%/g, '\\%')       // Escape %
        .replace(/_/g, '\\_');      // Escape _
}

// Encode for XML attribute
function encodeXmlAttribute(value) {
    return value
        .replace(/&/g, '&amp;')
        .replace(/</g, '&lt;')
        .replace(/>/g, '&gt;')
        .replace(/"/g, '&quot;')
        .replace(/'/g, '&apos;');
}

// Strict alphanumeric only
function encodeAlphanumeric(value) {
    return value.replace(/[^a-zA-Z0-9]/g, '');
}

// Data URLs with URL encoding

// Text data URL
const text = "Hello, World!";
const dataUrl = `data:text/plain,${encodeURIComponent(text)}`;
console.log(dataUrl);
// "data:text/plain,Hello%2C%20World!"

// HTML data URL
const html = "<h1>Hello!</h1>";
const htmlDataUrl = `data:text/html,${encodeURIComponent(html)}`;
console.log(htmlDataUrl);
// "data:text/html,%3Ch1%3EHello!%3C%2Fh1%3E"

// SVG data URL
const svg = '<svg><circle cx="50" cy="50" r="40"/></svg>';
const svgDataUrl = `data:image/svg+xml,${encodeURIComponent(svg)}`;

// Use in img tag
const img = document.createElement('img');
img.src = svgDataUrl;

// JavaScript data URL (be careful!)
const jsCode = "alert('Hello')";
const jsDataUrl = `data:text/javascript,${encodeURIComponent(jsCode)}`;
// Security warning: Can execute arbitrary code!

// Base64 is more common for binary data
const base64Data = btoa("Hello");
const base64Url = `data:text/plain;base64,${base64Data}`;

// Using browser DevTools console

// Encode
encodeURIComponent("Hello World");
// "Hello%20World"

encodeURI("https://example.com/Hello World");
// "https://example.com/Hello%20World"

// Decode
decodeURIComponent("Hello%20World");
// "Hello World"

// Parse current URL
const url = new URL(window.location.href);
console.log(url.searchParams.get('q'));

// Build URL
const params = new URLSearchParams();
params.append('q', 'search term');
params.append('lang', 'en');
console.log(params.toString());

// Test encoding
const test = "Special & Characters: 100%!";
console.log('Original:', test);
console.log('Encoded:', encodeURIComponent(test));
console.log('Decoded:', decodeURIComponent(encodeURIComponent(test)));

# Command-line URL encoding

# Using Python
python3 -c "import urllib.parse; print(urllib.parse.quote('Hello World'))"
# Hello%20World

python3 -c "import urllib.parse; print(urllib.parse.unquote('Hello%20World'))"
# Hello World

# Using Node.js
node -e "console.log(encodeURIComponent('Hello World'))"
# Hello%20World

# Using PHP
php -r "echo urlencode('Hello World');"
# Hello+World

php -r "echo rawurlencode('Hello World');"
# Hello%20World

# Using Perl
perl -MURI::Escape -e 'print uri_escape("Hello World")'
# Hello%20World

# Using jq (for JSON in URLs)
echo '{"name":"John"}' | jq -rR '@uri'
# %7B%22name%22%3A%22John%22%7D

// Test URL encoding in your application

// Unit test example (Jest)
describe('URL encoding', () => {
    test('encodes special characters', () => {
        const input = '[email protected]';
        const expected = 'user%40example.com';
        expect(encodeURIComponent(input)).toBe(expected);
    });

    test('handles spaces', () => {
        const input = 'Hello World';
        const expected = 'Hello%20World';
        expect(encodeURIComponent(input)).toBe(expected);
    });

    test('preserves safe characters', () => {
        const input = 'abc123-_.~';
        expect(encodeURIComponent(input)).toBe(input);
    });

    test('round-trip encoding', () => {
        const original = 'Complex: 100% & €20!';
        const encoded = encodeURIComponent(original);
        const decoded = decodeURIComponent(encoded);
        expect(decoded).toBe(original);
    });
});

// Integration test
test('API call with encoded parameters', async () => {
    const params = new URLSearchParams({
        q: 'test search',
        filter: 'type:article'
    });

    const response = await fetch(`/api/search?${params}`);
    expect(response.ok).toBe(true);
});