नियमावली

WEEGLOO API को code से call करते समय सभी requests, responses पर समान रूप से लागू होने वाली HTTP नियमावली एक ही जगह संक्षेप में दी गई है। response media type, आंशिक संशोधन (JSON Patch), और एक साथ संशोधन के टकराव को रोकने वाला X-Weegloo-Version header इसमें शामिल हैं। हर अलग संसाधन के endpoints उसके अपने संसाधन reference में बताए जाते हैं, और वे endpoints जिन नियमों का समान रूप से पालन करते हैं उनके लिए इस page का संदर्भ देते हैं।

Response media type

WEEGLOO API की response application/vnd.com.weegloo.v1+json;charset=UTF-8 media type का उपयोग करती है। यह सामान्य application/json नहीं है।

request में Accept: application/json न भेजें। इस value से media type की negotiation करने पर वह WEEGLOO के vendor type से मेल नहीं खाता, जिससे 406 Not Acceptable जैसी विफलता हो सकती है।

  • अनुशंसित: request में Accept header को छोड़ दें (उदाहरण: fetch में Accept न जोड़ें)।
  • यदि भेजना ही पड़े, तो response के समान vendor type application/vnd.com.weegloo.v1+json;charset=UTF-8 को ज्यों का त्यों उपयोग करें।

axios instance या साझा fetch wrapper बनाते समय यह सुनिश्चित करें कि डिफ़ॉल्ट value Accept: application/json को बाध्य न करे। (यह नियम application code पर लागू होता है। AI agent HTTP को सीधे call नहीं करता, बल्कि MCP tools का उपयोग करता है।)

आंशिक संशोधन (JSON Patch)

Content, Media, Content Type जैसे अधिकांश संसाधनों को PATCH से केवल एक हिस्सा चुनकर संशोधित किया जा सकता है। body RFC 6902 JSON Patch (नए टैब में खुलता है) format की एक array होती है। हर item में operation op, लक्ष्य स्थान को इंगित करने वाला JSON Pointer path path, और operation के अनुसार value या from होता है।

PATCH request का Content-Type header application/json-patch+json होना चाहिए। यह सामान्य application/json नहीं है।

नीचे एक field की केवल value बदलने का उदाहरण है।

[
  { "op": "replace", "path": "/fields/price/en-US", "value": 16500 }
]

पूरी body से बदलना हो तो PUT का उपयोग करें। PUT हमेशा पूरे संसाधन को प्रतिस्थापित करता है, इसलिए body में छोड़ा गया मान हटा दिया जाता है। कौन-सा endpoint PATCH का समर्थन करता है, यह हर संसाधन page के endpoint block में देखें।

समवर्तीता नियंत्रण (X-Weegloo-Version)

एक ही संसाधन को दो जगह से एक साथ बदलने पर एक तरफ का बदलाव दूसरी तरफ के बदलाव को मिटा सकता है। WEEGLOO इसे रोकने के लिए optimistic concurrency control का उपयोग करता है। संसाधन को संशोधित, delete, status परिवर्तन करते समय, request में वर्तमान sys.version को X-Weegloo-Version header में भेजें।

server इस value के संग्रहीत वर्तमान version के समान होने पर ही बदलाव स्वीकार करता है। header छूट जाने या value मेल न खाने पर (उदाहरण: इस बीच किसी और ने पहले बदलाव कर दिया हो और version बढ़ गया हो) यह टकराव त्रुटि के रूप में अस्वीकृत हो जाता है। ऐसी स्थिति में संसाधन को फिर से query करके नवीनतम sys.version प्राप्त करने के बाद बदलाव को दोबारा करें। त्रुटि response का format Errors में बताया गया है।

किस request के लिए यह आवश्यक है, यह इस प्रकार है।

श्रेणीX-Weegloo-Version
संशोधन (PUT), आंशिक संशोधन (PATCH)आवश्यक
status परिवर्तन (publish, unpublish, archive, unarchive)आवश्यक
निर्माण (POST)नहीं
delete (DELETE)केवल कुछ के लिए आवश्यक

जिन संसाधनों में version नहीं होता (ServiceUser, Scheduler), Delivery Access Token और Space Access Token के संशोधन, और ACMA के request इस header को स्वीकार नहीं करते। वास्तव में कौन-सा endpoint इस header की माँग करता है, यह हर संसाधन page के endpoint block में मौजूद requestHeaderSchema में देखें। स्वयं sys.version का अर्थ System Properties (sys) में बताया गया है।