सामान्य Query Parameters

WEEGLOO के list लाने वाले endpoints (जैसे GET /spaces/{spaceId}/contents, जो एक collection लौटाते हैं ऐसे GET) सामान्य query parameters स्वीकार करते हैं. इन parameters से आप एक page में कितने items लाने हैं उसकी सीमा तय करते हैं, sorting का मानदंड तय करते हैं, संबंधित resources साथ में लाते हैं, ज़रूरी fields ही चुनकर लेते हैं, शर्तों से list को संकुचित करते हैं, और अगले-पिछले page पर जाते हैं.

ये parameters resource के प्रकार से स्वतंत्र होकर एक ही तरीके से काम करते हैं. हर अलग resource reference केवल उस resource की अपनी शर्तें ही अलग से समझाता है, और यहाँ बताए गए सामान्य parameters के लिए इस page का संदर्भ देता है.

Parameters

order, select में उपयोग होने वाले sys fields के प्रकार System Properties (sys) में देखे जा सकते हैं.

Filter

Filter की शर्तें filter[] में लपेटे बिना, सीधे query parameter के रूप में भेजी जाती हैं. format {field}[{operator}]={value} है, और यदि आप operator छोड़ देते हैं तो इसे eq के रूप में समझा जाता है. उपयोग किए जा सकने वाले सभी operators के लिए नीचे Operators देखें.

{field}[{operator}]={value}

उदाहरण के लिए, केवल वे items लाने के लिए जिनका name टम्बलर से शुरू होता है, name[prefix]=टम्बलर भेजें. नियम और सावधानियाँ इस प्रकार हैं.

• शर्तों को filter[] में न लपेटें. filter[name[prefix]]=टम्बलर की तरह लपेटने पर यह काम नहीं करता.
• एक से अधिक शर्तें AND से जुड़ती हैं. केवल वे items बचते हैं जो उन सभी को पूरा करते हैं; OR खोज, जहाँ कई शर्तों में से किसी एक का मिलान पर्याप्त हो, समर्थित नहीं है. एक ही field में कई values में से किसी एक से मिलान करने के लिए in का उपयोग करें.
• fields. शर्त में locale शामिल होता है. उदाहरण के लिए, fields.file.ko-KR.mimeGroups=Image किसी Media list में से केवल image files रखता है, और sys.createdAt[gte]=2026-06-01T00:00:00Z केवल उस समय के बाद बनाए गए items रखता है.
• किसी Content list को fields. शर्त से filter या sort करने के लिए Content Type भी आवश्यक है. sys.contentType.sys.id को साथ में भेजें (केवल flat /contents के लिए); अकेला contentType= इसका विकल्प नहीं बनता. विवरण के लिए Content reference देखें.

Operators

RichText और Json fields खोज के लक्ष्य नहीं हैं, इसलिए इन्हें filter की शर्त में उपयोग नहीं किया जा सकता.

उन्नत खोज (Advanced Search)

regex, near, within operators और text पूर्ण-पाठ खोज केवल उन्नत खोज में काम करते हैं. उन्नत खोज को list लाने वाली request में header X-Weegloo-Advanced-Search: true जोड़कर चालू किया जाता है, और response में भी यही header साथ आता है.

• पूर्ण-पाठ खोज: पूर्ण-पाठ खोज चालू किए गए text field (LongText) पर eq का उपयोग करने पर, यह ठीक वैसे ही value के बजाय उस value को समाहित करने वाले items तक को आंशिक एवं समरूप मिलान से खोज लेता है. यदि उन्नत खोज चालू न हो या योजना (plan) उन्नत खोज प्रदान न करती हो, तो वही eq ठीक-ठीक मिलान के रूप में काम करता है.
• Location खोज: near (त्रिज्या) और within (बहुभुज) केवल Location field पर उपयोग होते हैं और केवल उन्नत खोज में काम करते हैं.
• जिन requests में उन्नत खोज उपलब्ध नहीं है उनमें regex, near, within भेजने पर इन्हें स्वीकार नहीं किया जाता.

Pagination (Cursor)

List response के body में एक links object होता है, और उसमें next, prev होते हैं. links.next अगले page तक जाने का पूरा path है.

/v1/spaces/HnQ32YiH/contents?limit=15&next=<cursor>

अगला page लाने के दो तरीके हैं. links.next के path को सीधे call करें, या links.next से next cursor value निकालकर अगली request के next parameter के रूप में भेजें. यदि links.next न हो तो यह अंतिम page है. पिछले page पर links.prev से इसी तरीके से जाया जाता है.

Page बदलते समय skip को बढ़ाकर उपयोग न करें. यदि lists के बीच items जुड़ते या हटते हैं तो skip की स्थिति खिसक जाती है और items छूट सकते हैं या दोहराए जा सकते हैं. Cursor (next, prev) में यह समस्या नहीं होती.

नीचे list response की संरचना का उदाहरण है. wrapper का sys.type TotalPageResponse है, items में items का array, और links में navigation paths होते हैं.

{
  "sys": { "type": "TotalPageResponse" },
  "limit": 15,
  "totalCount": 42,
  "items": [
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
        "type": "Content",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "createdAt": "2026-06-18T09:51:14.597Z",
        "updatedAt": "2026-06-18T09:51:44.128Z",
        "version": 2,
        "status": "Published"
      }
    }
  ],
  "links": {
    "self": "/v1/spaces/HnQ32YiH/contents?limit=15",
    "next": "/v1/spaces/HnQ32YiH/contents?limit=15&next=Q3Vyc29yVmFsdWU"
  }
}

totalCount शर्त से मेल खाने वाले कुल items की संख्या है, और limit इस response पर लागू एक page का आकार है. items में केवल उस page के items रखे जाते हैं.

संबंधित दस्तावेज़

• System Properties (sys): order, select में उपयोग होने वाले sys fields.
• Conventions: media type, JSON Patch, concurrency.