[{"data":1,"prerenderedAt":995},["ShallowReactive",2],{"guide-query-parameters-guide":3},{"id":4,"title":5,"body":6,"date":987,"description":988,"extension":989,"meta":990,"navigation":362,"path":991,"readingTime":372,"seo":992,"stem":993,"__hash__":994},"guides\u002Fguides\u002Fquery-parameters-guide.md","Query Parameters Guide: Structure, Encoding, and Best Practices",{"type":7,"value":8,"toc":962},"minimark",[9,14,23,33,44,48,51,93,99,103,106,218,228,231,252,316,319,323,326,388,391,395,398,454,458,483,486,490,493,497,503,550,556,566,570,576,606,611,620,623,627,630,747,758,762,766,769,775,778,782,785,791,800,804,807,861,868,872,919,923,941,945,958],[10,11,13],"h2",{"id":12},"what-are-query-parameters","What Are Query Parameters?",[15,16,17,18,22],"p",{},"Query parameters are the key-value pairs appended to a URL after the ",[19,20,21],"code",{},"?"," character. They pass data from the client to the server — search terms, filters, page numbers, and tracking codes all travel in query strings.",[24,25,30],"pre",{"className":26,"code":28,"language":29},[27],"language-text","https:\u002F\u002Fexample.com\u002Fsearch?q=hello&lang=en&page=2\n                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n                     query string\n","text",[19,31,28],{"__ignoreMap":32},"",[15,34,35,36,39,40,43],{},"Each pair follows the format ",[19,37,38],{},"key=value",", separated by ",[19,41,42],{},"&",". The server reads these parameters to generate the right response.",[10,45,47],{"id":46},"syntax-rules","Syntax Rules",[15,49,50],{},"A query string has strict formatting rules:",[52,53,54,61,66,71,78],"ul",{},[55,56,57,58,60],"li",{},"Starts with ",[19,59,21],{}," after the path",[55,62,63,64],{},"Contains key-value pairs: ",[19,65,38],{},[55,67,68,69],{},"Pairs separated by ",[19,70,42],{},[55,72,73,74,77],{},"Empty values are valid: ",[19,75,76],{},"key="," (value is an empty string)",[55,79,80,81,84,85,88,89,92],{},"Keys without ",[19,82,83],{},"="," are valid: ",[19,86,87],{},"key"," (value is ",[19,90,91],{},"null"," or empty, depending on the parser)",[24,94,97],{"className":95,"code":96,"language":29},[27],"?sort=price&order=asc&in_stock=\n ^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^\n key=value  key=value  key=(empty)\n",[19,98,96],{"__ignoreMap":32},[10,100,102],{"id":101},"encoding-rules","Encoding Rules",[15,104,105],{},"Not every character can appear raw in a query string. Reserved characters must be percent-encoded when used as data:",[107,108,109,125],"table",{},[110,111,112],"thead",{},[113,114,115,119,122],"tr",{},[116,117,118],"th",{},"Character",[116,120,121],{},"Encoded",[116,123,124],{},"Why Encode?",[126,127,128,146,160,174,189,204],"tbody",{},[113,129,130,134,143],{},[131,132,133],"td",{},"Space",[131,135,136,139,140],{},[19,137,138],{},"%20"," or ",[19,141,142],{},"+",[131,144,145],{},"Spaces break URL parsing",[113,147,148,152,157],{},[131,149,150],{},[19,151,42],{},[131,153,154],{},[19,155,156],{},"%26",[131,158,159],{},"Separates parameters",[113,161,162,166,171],{},[131,163,164],{},[19,165,83],{},[131,167,168],{},[19,169,170],{},"%3D",[131,172,173],{},"Assigns values to keys",[113,175,176,181,186],{},[131,177,178],{},[19,179,180],{},"#",[131,182,183],{},[19,184,185],{},"%23",[131,187,188],{},"Starts the fragment",[113,190,191,196,201],{},[131,192,193],{},[19,194,195],{},"%",[131,197,198],{},[19,199,200],{},"%25",[131,202,203],{},"Starts an encoding",[113,205,206,210,215],{},[131,207,208],{},[19,209,142],{},[131,211,212],{},[19,213,214],{},"%2B",[131,216,217],{},"Interpreted as space in form encoding",[219,220,222,223,225,226],"h3",{"id":221},"space-encoding-20-vs","Space Encoding: ",[19,224,138],{}," vs ",[19,227,142],{},[15,229,230],{},"The treatment of spaces causes frequent confusion:",[52,232,233,241],{},[55,234,235,240],{},[236,237,238],"strong",{},[19,239,138],{}," — standard percent-encoding per RFC 3986, valid everywhere in a URL",[55,242,243,247,248,251],{},[236,244,245],{},[19,246,142],{}," — shorthand from ",[19,249,250],{},"application\u002Fx-www-form-urlencoded",", valid only in query strings",[24,253,257],{"className":254,"code":255,"language":256,"meta":32,"style":32},"language-javascript shiki shiki-themes github-light github-dark","\u002F\u002F JavaScript behavior\nencodeURIComponent('hello world')  \u002F\u002F \"hello%20world\" — always %20\nnew URLSearchParams({ q: 'hello world' }).toString()  \u002F\u002F \"q=hello+world\" — uses +\n","javascript",[19,258,259,268,289],{"__ignoreMap":32},[260,261,264],"span",{"class":262,"line":263},"line",1,[260,265,267],{"class":266},"sJ8bj","\u002F\u002F JavaScript behavior\n",[260,269,271,275,279,283,286],{"class":262,"line":270},2,[260,272,274],{"class":273},"sScJk","encodeURIComponent",[260,276,278],{"class":277},"sVt8B","(",[260,280,282],{"class":281},"sZZnC","'hello world'",[260,284,285],{"class":277},")  ",[260,287,288],{"class":266},"\u002F\u002F \"hello%20world\" — always %20\n",[260,290,292,296,299,302,304,307,310,313],{"class":262,"line":291},3,[260,293,295],{"class":294},"szBVR","new",[260,297,298],{"class":273}," URLSearchParams",[260,300,301],{"class":277},"({ q: ",[260,303,282],{"class":281},[260,305,306],{"class":277}," }).",[260,308,309],{"class":273},"toString",[260,311,312],{"class":277},"()  ",[260,314,315],{"class":266},"\u002F\u002F \"q=hello+world\" — uses +\n",[15,317,318],{},"When decoding, always use the right method for how the value was encoded. Mixing them produces incorrect results.",[219,320,322],{"id":321},"double-encoding-trap","Double Encoding Trap",[15,324,325],{},"If you encode a value that is already encoded, you break the data:",[24,327,329],{"className":254,"code":328,"language":256,"meta":32,"style":32},"\u002F\u002F WRONG: double encoding\nencodeURIComponent(encodeURIComponent('a&b'))\n\u002F\u002F \"a%2526b\" — the %26 got re-encoded to %2526\n\n\u002F\u002F CORRECT: encode once\nencodeURIComponent('a&b')\n\u002F\u002F \"a%26b\"\n",[19,330,331,336,352,357,364,370,382],{"__ignoreMap":32},[260,332,333],{"class":262,"line":263},[260,334,335],{"class":266},"\u002F\u002F WRONG: double encoding\n",[260,337,338,340,342,344,346,349],{"class":262,"line":270},[260,339,274],{"class":273},[260,341,278],{"class":277},[260,343,274],{"class":273},[260,345,278],{"class":277},[260,347,348],{"class":281},"'a&b'",[260,350,351],{"class":277},"))\n",[260,353,354],{"class":262,"line":291},[260,355,356],{"class":266},"\u002F\u002F \"a%2526b\" — the %26 got re-encoded to %2526\n",[260,358,360],{"class":262,"line":359},4,[260,361,363],{"emptyLinePlaceholder":362},true,"\n",[260,365,367],{"class":262,"line":366},5,[260,368,369],{"class":266},"\u002F\u002F CORRECT: encode once\n",[260,371,373,375,377,379],{"class":262,"line":372},6,[260,374,274],{"class":273},[260,376,278],{"class":277},[260,378,348],{"class":281},[260,380,381],{"class":277},")\n",[260,383,385],{"class":262,"line":384},7,[260,386,387],{"class":266},"\u002F\u002F \"a%26b\"\n",[15,389,390],{},"Check whether data is already encoded before encoding it again.",[10,392,394],{"id":393},"array-parameters","Array Parameters",[15,396,397],{},"Passing arrays in query strings has no single standard. Three common patterns exist:",[107,399,400,413],{},[110,401,402],{},[113,403,404,407,410],{},[116,405,406],{},"Style",[116,408,409],{},"Example",[116,411,412],{},"Used By",[126,414,415,428,441],{},[113,416,417,420,425],{},[131,418,419],{},"Repeated key",[131,421,422],{},[19,423,424],{},"?id=1&id=2&id=3",[131,426,427],{},"PHP, Express, most frameworks",[113,429,430,433,438],{},[131,431,432],{},"Bracket notation",[131,434,435],{},[19,436,437],{},"?id[]=1&id[]=2",[131,439,440],{},"PHP, Rails",[113,442,443,446,451],{},[131,444,445],{},"Comma-separated",[131,447,448],{},[19,449,450],{},"?ids=1,2,3",[131,452,453],{},"Custom APIs, some REST services",[219,455,457],{"id":456},"which-should-you-use","Which should you use?",[52,459,460,469,478],{},[55,461,462,464,465,468],{},[236,463,419],{}," — the most widely supported. Most server frameworks parse ",[19,466,467],{},"?id=1&id=2"," into an array automatically.",[55,470,471,473,474,477],{},[236,472,432],{}," — explicit but requires server-side support for ",[19,475,476],{},"[]"," parsing.",[55,479,480,482],{},[236,481,445],{}," — compact but forces you to split strings server-side. Does not work if values contain commas.",[15,484,485],{},"Pick one convention and document it in your API specification.",[10,487,489],{"id":488},"pagination-patterns","Pagination Patterns",[15,491,492],{},"Query parameters drive pagination in nearly every list API. Two main patterns dominate:",[219,494,496],{"id":495},"offset-based-pagination","Offset-Based Pagination",[24,498,501],{"className":499,"code":500,"language":29},[27],"GET \u002Fapi\u002Fproducts?page=2&limit=20\n",[19,502,500],{"__ignoreMap":32},[107,504,505,515],{},[110,506,507],{},[113,508,509,512],{},[116,510,511],{},"Parameter",[116,513,514],{},"Purpose",[126,516,517,527,537],{},[113,518,519,524],{},[131,520,521],{},[19,522,523],{},"page",[131,525,526],{},"Current page number (1-based)",[113,528,529,534],{},[131,530,531],{},[19,532,533],{},"limit",[131,535,536],{},"Items per page",[113,538,539,544],{},[131,540,541],{},[19,542,543],{},"offset",[131,545,546,547,549],{},"Alternative to ",[19,548,523],{}," — skip N items",[15,551,552,555],{},[236,553,554],{},"Pros:"," Simple, allows jumping to any page.",[15,557,558,561,562,565],{},[236,559,560],{},"Cons:"," Slow for large offsets (",[19,563,564],{},"OFFSET 100000"," scans 100K rows). Items may be skipped or duplicated if data changes between requests.",[219,567,569],{"id":568},"cursor-based-pagination","Cursor-Based Pagination",[24,571,574],{"className":572,"code":573,"language":29},[27],"GET \u002Fapi\u002Fproducts?cursor=abc123&limit=20\n",[19,575,573],{"__ignoreMap":32},[107,577,578,586],{},[110,579,580],{},[113,581,582,584],{},[116,583,511],{},[116,585,514],{},[126,587,588,598],{},[113,589,590,595],{},[131,591,592],{},[19,593,594],{},"cursor",[131,596,597],{},"Opaque token pointing to the position",[113,599,600,604],{},[131,601,602],{},[19,603,533],{},[131,605,536],{},[15,607,608,610],{},[236,609,554],{}," Consistent results even when data changes. Fast — no offset scanning.",[15,612,613,615,616,619],{},[236,614,560],{}," No random page access. Requires the client to follow ",[19,617,618],{},"next_cursor"," links.",[15,621,622],{},"Use cursor-based pagination for large or frequently changing datasets. Use offset-based for small, static collections where page jumping matters.",[10,624,626],{"id":625},"rest-api-parameter-conventions","REST API Parameter Conventions",[15,628,629],{},"Well-designed REST APIs follow consistent parameter naming:",[107,631,632,642],{},[110,633,634],{},[113,635,636,638,640],{},[116,637,511],{},[116,639,514],{},[116,641,409],{},[126,643,644,659,674,689,704,719,733],{},[113,645,646,651,654],{},[131,647,648],{},[19,649,650],{},"filter",[131,652,653],{},"Apply conditions",[131,655,656],{},[19,657,658],{},"?filter=status:active",[113,660,661,666,669],{},[131,662,663],{},[19,664,665],{},"sort",[131,667,668],{},"Sort results",[131,670,671],{},[19,672,673],{},"?sort=created_at:desc",[113,675,676,681,684],{},[131,677,678],{},[19,679,680],{},"fields",[131,682,683],{},"Select specific fields",[131,685,686],{},[19,687,688],{},"?fields=id,name,email",[113,690,691,696,699],{},[131,692,693],{},[19,694,695],{},"embed",[131,697,698],{},"Include related resources",[131,700,701],{},[19,702,703],{},"?embed=author,comments",[113,705,706,711,714],{},[131,707,708],{},[19,709,710],{},"q",[131,712,713],{},"Search query",[131,715,716],{},[19,717,718],{},"?q=blue+shirt",[113,720,721,725,728],{},[131,722,723],{},[19,724,533],{},[131,726,727],{},"Max items to return",[131,729,730],{},[19,731,732],{},"?limit=50",[113,734,735,739,742],{},[131,736,737],{},[19,738,523],{},[131,740,741],{},"Page number",[131,743,744],{},[19,745,746],{},"?page=3",[15,748,749,750,753,754,757],{},"Keep parameter names lowercase and use underscores for multi-word names: ",[19,751,752],{},"created_at",", not ",[19,755,756],{},"createdAt",". Consistency matters more than the specific convention — just pick one and stick to it.",[10,759,761],{"id":760},"security-risks","Security Risks",[219,763,765],{"id":764},"sensitive-data-in-urls","Sensitive Data in URLs",[15,767,768],{},"Query parameters appear in browser history, server logs, referrer headers, and analytics tools. Never put secrets in a URL:",[24,770,773],{"className":771,"code":772,"language":29},[27],"\u002F\u002F DANGEROUS — exposes the token\nGET \u002Fapi\u002Fdata?token=abc123secret\n\n\u002F\u002F SAFE — send via header\nGET \u002Fapi\u002Fdata\nAuthorization: Bearer abc123secret\n",[19,774,772],{"__ignoreMap":32},[15,776,777],{},"Sensitive values — API keys, passwords, session tokens — must travel in headers or request bodies, never in query strings.",[219,779,781],{"id":780},"parameter-injection","Parameter Injection",[15,783,784],{},"Unvalidated query parameters can inject commands or manipulate backend logic:",[24,786,789],{"className":787,"code":788,"language":29},[27],"\u002F\u002F SQL injection via sort parameter\n?sort=price; DROP TABLE products--\n\n\u002F\u002F NoSQL injection via filter\n?filter[$gt]=\n",[19,790,788],{"__ignoreMap":32},[15,792,793,794,799],{},"Always validate and sanitize query parameters server-side. Use allowlists for sort fields and filter keys. For more on URL-based attacks, see our ",[795,796,798],"a",{"href":797},"\u002Fguides\u002Furl-security-best-practices","URL Security Best Practices"," guide.",[219,801,803],{"id":802},"url-length-limits","URL Length Limits",[15,805,806],{},"Browsers and servers impose URL length limits:",[107,808,809,819],{},[110,810,811],{},[113,812,813,816],{},[116,814,815],{},"Component",[116,817,818],{},"Limit",[126,820,821,829,837,845,853],{},[113,822,823,826],{},[131,824,825],{},"Chrome",[131,827,828],{},"~2 MB",[113,830,831,834],{},[131,832,833],{},"Firefox",[131,835,836],{},"~65,536 characters",[113,838,839,842],{},[131,840,841],{},"Internet Explorer",[131,843,844],{},"2,083 characters",[113,846,847,850],{},[131,848,849],{},"Apache",[131,851,852],{},"8,190 characters",[113,854,855,858],{},[131,856,857],{},"Nginx",[131,859,860],{},"4,096–8,192 characters",[15,862,863,864,867],{},"If your query string exceeds a few thousand characters, move data to the request body using ",[19,865,866],{},"POST",".",[10,869,871],{"id":870},"key-takeaways","Key Takeaways",[52,873,874,885,893,896,899,913,916],{},[55,875,876,877,879,880,882,883],{},"Query strings start with ",[19,878,21],{}," and contain ",[19,881,38],{}," pairs separated by ",[19,884,42],{},[55,886,887,888,139,890,892],{},"Spaces can be ",[19,889,138],{},[19,891,142],{},", but the two are not interchangeable — know which encoding your system uses",[55,894,895],{},"Array parameters have three styles: repeated keys, brackets, and comma-separated",[55,897,898],{},"Cursor-based pagination outperforms offset-based for large datasets",[55,900,901,902,904,905,904,907,909,910,912],{},"REST APIs commonly use ",[19,903,650],{},", ",[19,906,665],{},[19,908,680],{},", and ",[19,911,695],{}," parameters",[55,914,915],{},"Never place sensitive data in query strings — it leaks into logs and history",[55,917,918],{},"Validate all query parameters server-side to prevent injection attacks",[10,920,922],{"id":921},"related-guides","Related Guides",[52,924,925,931,935],{},[55,926,927],{},[795,928,930],{"href":929},"\u002Fguides\u002Furl-structure-explained","URL Structure Explained",[55,932,933],{},[795,934,798],{"href":797},[55,936,937],{},[795,938,940],{"href":939},"\u002Fguides\u002Furl-encoding-guide","URL Encoding Guide",[10,942,944],{"id":943},"try-it-yourself","Try It Yourself",[15,946,947,948,952,953,957],{},"Parse and inspect query parameters instantly with our free ",[795,949,951],{"href":950},"\u002Ftools\u002Furl-parser","URL Parser",". Need to encode or decode parameter values? Try the ",[795,954,956],{"href":955},"\u002Ftools\u002Furl-encoder","URL Encoder\u002FDecoder"," — it handles percent-encoding, plus signs, and special characters correctly in one click.",[959,960,961],"style",{},"html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":32,"searchDepth":270,"depth":270,"links":963},[964,965,966,971,974,978,979,984,985,986],{"id":12,"depth":270,"text":13},{"id":46,"depth":270,"text":47},{"id":101,"depth":270,"text":102,"children":967},[968,970],{"id":221,"depth":291,"text":969},"Space Encoding: %20 vs +",{"id":321,"depth":291,"text":322},{"id":393,"depth":270,"text":394,"children":972},[973],{"id":456,"depth":291,"text":457},{"id":488,"depth":270,"text":489,"children":975},[976,977],{"id":495,"depth":291,"text":496},{"id":568,"depth":291,"text":569},{"id":625,"depth":270,"text":626},{"id":760,"depth":270,"text":761,"children":980},[981,982,983],{"id":764,"depth":291,"text":765},{"id":780,"depth":291,"text":781},{"id":802,"depth":291,"text":803},{"id":870,"depth":270,"text":871},{"id":921,"depth":270,"text":922},{"id":943,"depth":270,"text":944},"2026-05-28","Everything about URL query parameters — syntax, encoding rules, arrays, pagination patterns, and REST API conventions.","md",{"immutable":362},"\u002Fguides\u002Fquery-parameters-guide",{"title":5,"description":988},"guides\u002Fquery-parameters-guide","ROM9nqHUeVlgur56YjrngjPGnyqpZDyY8GYa2AEOwtM",1780401326800]