REST API में Query Parameters को सही तरीके से Encode कैसे करें

Query Parameters को Encoding की ज़रूरत क्यों होती है

REST API में query strings एक संरचित फ़ॉर्मेट का उपयोग करती हैं जहाँ key-value जोड़े & से अलग किए जाते हैं और keys को values से = द्वारा अलग किया जाता है। यदि किसी parameter की value में इनमें से कोई delimiter अक्षर, या #, +, या स्पेस जैसे अन्य reserved अक्षर मौजूद हों, तो query string की संरचना टूट जाती है और सर्वर को गलत डेटा प्राप्त होता है।

इस उदाहरण पर विचार करें: आप किसी API में "salt & pepper" खोजना चाहते हैं। Encoding के बिना, URL /search?q=salt & pepper सर्वर को बताता है कि यहाँ दो parameters हैं: q=salt और pepper (जिसकी कोई value नहीं है)। सही encoding के साथ, /search?q=salt%20%26%20pepper सही ढंग से एक ही parameter q को "salt & pepper" value के साथ भेजता है।

सही होने के अलावा, उचित encoding सुरक्षा कमज़ोरियों को भी रोकती है। URLs में बिना encode किया गया user input injection attacks, cache poisoning और अन्य exploits का कारण बन सकता है। parameter values को URLs में शामिल करने से पहले हमेशा encode करें।

विभिन्न भाषाओं में Encoding

हर प्रमुख programming भाषा URL encoding के लिए built-in functions प्रदान करती है। सबसे लोकप्रिय भाषाओं में query parameters को सही तरीके से encode करने का तरीका यहाँ दिया गया है।

// JavaScript
// अलग-अलग parameter values के लिए encodeURIComponent() का उपयोग करें
const query = 'price >= 100 & category = books';
const url = 'https://api.example.com/search?q=' + encodeURIComponent(query);
// "https://api.example.com/search?q=price%20%3E%3D%20100%20%26%20category%20%3D%20books"

// या कई parameters के लिए URLSearchParams का उपयोग करें
const params = new URLSearchParams({
  q: 'price >= 100 & category = books',
  page: '1',
  sort: 'price'
});
const url2 = 'https://api.example.com/search?' + params.toString();

# Python
from urllib.parse import urlencode, quote

# कई parameters के लिए urlencode का उपयोग
params = {
    'q': 'price >= 100 & category = books',
    'page': 1,
    'sort': 'price'
}
query_string = urlencode(params)
url = f'https://api.example.com/search?{query_string}'

# किसी एकल value के लिए quote का उपयोग
value = quote('price >= 100 & category = books', safe='')
url = f'https://api.example.com/search?q={value}'

// Java
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

String query = "price >= 100 & category = books";
String encoded = URLEncoder.encode(query, StandardCharsets.UTF_8);
// "price+%3E%3D+100+%26+category+%3D+books"
// ध्यान दें: URLEncoder स्पेस के लिए + का उपयोग करता है (form encoding)

// RFC 3986 encoding के लिए, + को %20 से बदलें
String rfc3986 = encoded.replace("+", "%20");
String url = "https://api.example.com/search?q=" + rfc3986;

// C#
using System.Net;
using System.Web;

string query = "price >= 100 & category = books";

// Uri.EscapeDataString RFC 3986 का पालन करता है
string encoded = Uri.EscapeDataString(query);
// "price%20%3E%3D%20100%20%26%20category%20%3D%20books"

// HttpUtility.UrlEncode form encoding का उपयोग करता है (स्पेस के लिए +)
string formEncoded = HttpUtility.UrlEncode(query);
// "price+%3e%3d+100+%26+category+%3d+books"

// Go
package main

import (
    "fmt"
    "net/url"
)

func main() {
    // url.QueryEscape query strings के लिए encode करता है (स्पेस के लिए +)
    encoded := url.QueryEscape("price >= 100 & category = books")
    // "price+%3E%3D+100+%26+category+%3D+books"

    // url.PathEscape path segments के लिए encode करता है (स्पेस के लिए %20)
    pathEncoded := url.PathEscape("my file name.pdf")
    // "my%20file%20name.pdf"

    // query strings बनाने के लिए url.Values का उपयोग
    params := url.Values{}
    params.Set("q", "price >= 100 & category = books")
    params.Set("page", "1")
    queryString := params.Encode()
    fmt.Println(queryString)
}

Arrays और Nested Objects को Encode करना

REST APIs को अक्सर query parameters के रूप में arrays या nested objects स्वीकार करने की ज़रूरत होती है। इन जटिल प्रकारों को encode करने के लिए कोई एकल मानक नहीं है, इसलिए अलग-अलग APIs अलग-अलग परंपराओं का उपयोग करती हैं।

// दोहराई गई keys (सबसे व्यापक रूप से समर्थित)
// GET /api/items?tag=javascript&tag=python&tag=go
const params = new URLSearchParams();
['javascript', 'python', 'go'].forEach(tag => params.append('tag', tag));

// Bracket notation (PHP, Rails, qs के साथ Express में सामान्य)
// GET /api/items?tags[]=javascript&tags[]=python&tags[]=go
// इसे मैन्युअल रूप से encode करना होगा:
const tags = ['javascript', 'python', 'go'];
const qs = tags.map(t => 'tags[]=' + encodeURIComponent(t)).join('&');

// Comma-separated (सरल लेकिन सीमित)
// GET /api/items?tags=javascript,python,go
const tagList = encodeURIComponent('javascript,python,go');

// Nested objects (bracket notation)
// GET /api/search?filter[status]=active&filter[min_price]=10
// Python में:
params = {
    'filter[status]': 'active',
    'filter[min_price]': '10'
}

अपेक्षित फ़ॉर्मेट के लिए हमेशा अपनी API documentation जाँचें। एक नई API डिज़ाइन करते समय, दोहराई गई keys वाला तरीका programming भाषाओं और HTTP libraries के बीच सबसे अधिक portable होता है।

Server-Side Decoding की सर्वोत्तम प्रथाएँ

सर्वर की ओर आने वाली requests को संभालते समय, अधिकांश web frameworks आपके लिए query parameters को स्वचालित रूप से decode कर देते हैं। हालाँकि, मज़बूत server-side handling के लिए कुछ महत्वपूर्ण बातों को ध्यान में रखना ज़रूरी है।

• अधिकांश frameworks (Express, Django, Spring, ASP.NET) query parameters को स्वचालित रूप से decode करते हैं। उन्हें दोबारा मैन्युअल रूप से decode न करें, अन्यथा double-decode हो जाएगा।
• decode की गई values का उपयोग करने से पहले उन्हें अपेक्षित प्रकारों और श्रेणियों के विरुद्ध validate करें।
• web server स्तर पर अधिकतम URL length सीमाएँ सेट करें (आमतौर पर 2048 या 8192 अक्षर)।
• उस स्थिति को संभालें जहाँ content type के आधार पर + का अर्थ या तो स्पेस या शाब्दिक plus चिह्न हो सकता है।
• debugging के लिए मूल (encoded) URL को log करें, क्योंकि logs में decode की गई values भ्रामक हो सकती हैं।

// Express.js - parameters स्वचालित रूप से decode हो जाते हैं
app.get('/search', (req, res) => {
  const query = req.query.q; // पहले से ही decoded है

  // ऐसा न करें: decodeURIComponent(req.query.q)

  // input को validate करें
  if (typeof query !== 'string' || query.length > 200) {
    return res.status(400).json({ error: 'Invalid query parameter' });
  }

  // decode की गई value का सुरक्षित रूप से उपयोग करें
  const results = search(query);
  res.json(results);
});

सुरक्षा संबंधी विचार

query parameter की उचित encoding API सुरक्षा का एक अहम हिस्सा है। पालन करने योग्य सबसे महत्वपूर्ण सुरक्षा प्रथाएँ यहाँ दी गई हैं।

• client-side encoding पर कभी भरोसा न करें। भले ही client ने उन्हें सही ढंग से encode किया हो, decode किए गए parameters को सर्वर पर हमेशा validate और sanitize करें।
• double-encoding attacks से सावधान रहें। कोई attacker उन input filters को दरकिनार करने के लिए हानिकारक अक्षरों को दो बार encode कर सकता है जो केवल एक बार decode करते हैं। सुनिश्चित करें कि आपके security filters पूरी तरह decode की गई values देखें।
• path traversal को रोकें। path parameters में %2e%2e%2f (../) जैसे encoded sequences का उपयोग इच्छित directory के बाहर की फ़ाइलों तक पहुँचने के लिए किया जा सकता है। फ़ाइल operations से पहले paths को decode और validate करें।
• parameterized queries का उपयोग करें। URL decoding के बाद भी, user input को SQL या NoSQL queries में सीधे कभी concatenate न करें। parameterized queries या किसी ORM का उपयोग करें।
• URL length सीमित करें। बेहद लंबी query strings denial-of-service का कारण बन सकती हैं। अपने web server को उचित length से अधिक लंबे URLs को अस्वीकार करने के लिए configure करें।
• output को भी encode करें। query parameter values को HTML responses में वापस दर्शाते समय, cross-site scripting (XSS) attacks को रोकने के लिए HTML entity encoding लागू करें।