Filtering, Sorting और Field Selection

छोटी, एकरूप परिपाटियाँ

Filtering (?status=paid&created_after=2026-09-01), sorting (?sort=-created_at,total, जहाँ - का मतलब अवरोही) और field selection (?fields=id,total) के लिए query parameters उपयोग करें, या संबंधित resources जोड़ने (?expand=customer) के लिए expand parameter, ताकि round trips बचें। सभी collections में नाम और formats एक-से रखें, जिन fields पर clients filter या sort कर सकें उनकी whitelist बनाएँ (और उन्हें index करें), मानों को सख़्ती से validate करें, और defaults दस्तावेज़ित करें। जब तक सचमुच ज़रूरत न हो, अपनी query भाषा न गढ़ें; सरल से शुरू करें और नए वैकल्पिक parameters से बढ़ाएँ, जो backward-compatible बदलाव है।

परिपाटियों वाला अनुरोध

एक अनुरोध filtering, sorting, field selection और paging को जोड़ता है। अज्ञात parameters को चुपचाप अनदेखा करने की जगह साफ़ 400 देना चाहिए।

GET /v2/orders?status=paid&created_after=2026-09-01&sort=-created_at&fields=id,total,customer_id&limit=50

200 OK
{ "data": [ {"id": "ord_91", "total": 1200, "customer_id": "cus_7"}, ... ],
  "next_cursor": "eyJhZnRlciI6ICJvcmRfNDIifQ==" }

असीमित queries की अनुमति न दें

limit की सीमा रखें, sortable fields को indexed तक सीमित करें और तारीख़ों की सीमाएँ बाँधें। एक चतुर अनुरोध पूरा database स्कैन न कर सके।

त्वरित जाँच: `?sort=-created_at` का परिपाटी से क्या मतलब है?

• आरोही क्रम में sort करें
• created_at हटाएँ
• created_at के अवरोही क्रम में sort करें
• created_at छिपाएँ