नियमावली

WEEGLOO API को code से call करते समय सभी requests, responses पर समान रूप से लागू होने वाली HTTP नियमावली एक ही जगह संक्षेप में दी गई है. response media type, आंशिक संशोधन (JSON Patch), और एक साथ संशोधन के टकराव को रोकने वाला X-Weegloo-Version header इसमें शामिल हैं. हर अलग resource के endpoints उसके अपने resource 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 जैसे अधिकांश resources को 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 resource की पूरी body (या जहाँ endpoint contract अनुमति देता है, वहाँ केवल बदले जाने वाले हिस्से वाली आंशिक body) से प्रतिस्थापित करता है. कौन-सा endpoint PATCH का समर्थन करता है, और PUT पूर्ण प्रतिस्थापन है या आंशिक प्रतिस्थापन, यह हर resource page के endpoint block में देखें.

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

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

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

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

जिन resources में version नहीं होता (ServiceUser) वे इस header को स्वीकार नहीं करते. वास्तव में कौन-सा endpoint इस header की माँग करता है, यह हर resource page के endpoint block में मौजूद requestHeaderSchema में देखें. स्वयं sys.version का अर्थ System Properties (sys) में बताया गया है.

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

• System Properties (sys): X-Weegloo-Version में भेजा जाने वाला sys.version.
• सामान्य Query Parameters: list query, pagination.
• Errors: WGL409005 जैसे त्रुटि codes.