शब्दावली

टीएल;डीआर:

• HTTP अनुरोध JSON:API की resources पर किए जाते हैं। इन्हें resource objects से भ्रमित न करें।
• क्लाइंट को जो JSON ऑब्जेक्ट प्राप्त होता है, उसे दस्तावेज़ (document) कहा जाता है।
• एक दस्तावेज़ हमेशा JSON ऑब्जेक्ट होता है और इसमें data कुंजी के अंतर्गत primary data होता है।
• उस कुंजी के अंतर्गत मौजूद डेटा को resource objects या resource identifier objects कहा जाता है।
• जब आप अनुरोध करते हैं कि संबंधित डेटा दस्तावेज़ में एम्बेड किया जाए, तो वह compound document बन जाता है।
• एक compound document वह है जिसमें शीर्ष-स्तरीय ऑब्जेक्ट में included कुंजी होती है।
• वे संसाधन जो कई resource objects लौटाते हैं, उन्हें collection resources कहा जाता है।
• वे संसाधन जो एक resource object लौटाते हैं, उन्हें individual resources कहा जाता है।
• वे संसाधन जो resource objects के बीच संबंधों के बारे में जानकारी लौटाते हैं, उन्हें relationship resources कहा जाता है।
• Drupal की भाषा में:
  • Resource Objects → Entities
  • Resource Identifier Objects → Entity reference field Items
  • Document → Request/response JSON payload

नीचे JSON:API मॉड्यूल का वर्णन करते समय उपयोग किए जाने वाले शब्दों और अवधारणाओं का संक्षिप्त विवरण दिया गया है।

यह शब्दावली JSON:API विनिर्देशन से काफ़ी मेल खाती है, हालाँकि यह परिभाषाओं को Drupal के सापेक्ष प्रस्तुत करने का प्रयास करती है। यह उन सूक्ष्म पहलुओं को भी विस्तार से बताती है जो किसी नए पाठक—जो विनिर्देशन या विनिर्देशन पढ़ने के तरीके—से भलीभाँति परिचित नहीं है, के लिए स्पष्ट न हों।

इनमें से कई परिभाषाएँ एक-दूसरे से जुड़ी हुई हैं। पेज के नीचे एक आरेख भी है जो इन शब्दों को उनके संदर्भ में दिखाता है।

Resource

एक ऐसा स्थान जहाँ से JSON:API का response document प्राप्त किया जा सकता है। किसी resource को उसके URL (Universal Resource Locator) के द्वारा पाया जा सकता है। इसे “resource object” से भ्रमित नहीं होना चाहिए। किसी resource का एप्लिकेशन के डेटा के साथ एक-से-एक सामंजस्य नहीं होता।

Drupal की भाषा में, JSON:API का resource किसी entity का पर्यायवाची नहीं है। इसके बजाय, resource वह स्थान है जहाँ किसी अवधारणा का डेटा प्राप्त किया जा सकता है। उदाहरण के लिए, वह अवधारणा “node--article प्रकार के resource objects का एक संग्रह” हो सकती है या “किसी विशेष article node के field_tags entity reference फ़ील्ड का निरूपण” हो सकती है।

Response Document

JSON:API के किसी resource से लौटाई गई JSON-एन्कोडेड प्रतिक्रिया बॉडी। यही वह “envelope” है जिसके माध्यम से डेटा या त्रुटियाँ HTTP क्लाइंट तक पहुँचाई जाती हैं। इसे कभी-कभी शीर्ष-स्तरीय ऑब्जेक्ट (top-level object) भी कहा जाता है। जब किसी दस्तावेज़ में included document member होता है, तो इसे एक compound document कहा जाता है।

Compound Document

वह response document जिसमें included document member होता है। एक compound document संबंधित resource objects को प्रतिक्रिया के primary data के साथ एम्बेड करके HTTP अनुरोधों की संख्या कम करने के लिए उपयोग किया जा सकता है। किसी अनुरोध के URL में include क्वेरी पैरामीटर जोड़कर compound document प्राप्त किया जा सकता है।

Error Document

वह response document जिसमें errors document member होता है, जो एक या अधिक error objects को रखता है। इसमें कभी भी data document member नहीं होता। ऐसे response का HTTP status code हमेशा 4xx या 5xx श्रेणी का होगा।

Individual Resource

वह resource जिसके response document के data member के रूप में एक ही resource object होता है। पर्याप्त प्राधिकरण होने पर यह resource पढ़ने योग्य (readable) और परिवर्तनीय (mutable) होता है। Drupal की भाषा में, इसका उपयोग किसी एक entity को ‘view’, ‘update’ या ‘delete’ करने के लिए किया जा सकता है। इसका उपयोग किसी entity को ‘create’ करने के लिए नहीं किया जा सकता।

Collection Resource

वह resource जिसके response document के data member के रूप में कई resource objects होते हैं। पर्याप्त प्राधिकरण होने पर यह resource पढ़ने और लिखने (writeable) दोनों योग्य होता है। ऐसे resources को paginate, filter और sort किया जा सकता है। Drupal की भाषा में, इसका उपयोग नई entity ‘create’ करने के लिए किया जा सकता है। इसका उपयोग संग्रह में entities को ‘update’ या ‘delete’ करने के लिए नहीं किया जा सकता।

Relationship Resource

वह resource जिसके response document का शीर्ष-स्तरीय ऑब्जेक्ट एक relationship object होता है। इसमें एक या अधिक resource identifier objects होते हैं, जिनमें से प्रत्येक किसी resource object से किसी अन्य resource object के लिए एक संदर्भ (reference) का प्रतिनिधित्व करता है। पर्याप्त प्राधिकरण होने पर यह resource पढ़ने योग्य और परिवर्तनीय होता है। Drupal की भाषा में, इसका उपयोग किसी एक entity reference फ़ील्ड के items को ‘view’ या ‘edit’ करने के लिए किया जा सकता है।

Related Resource

वह resource जो एक विशेष प्रकार का collection resource होता है, और जिसके response document के data member के रूप में एक या अधिक resource objects होते हैं। इस संग्रह के resource objects किसी संदर्भित resource object पर स्थित किसी relationship के विषय (subjects) होते हैं। यह resource केवल पढ़ने योग्य है (read-only)। Drupal की भाषा में, इसका उपयोग उन entities को ‘view’ करने के लिए किया जा सकता है जो किसी entity reference फ़ील्ड द्वारा संदर्भित होती हैं, लेकिन उन entities को ‘update’ करने या उस entity reference फ़ील्ड को ‘edit’ करने के लिए नहीं।

Document member

वह JSON ऑब्जेक्ट जो शीर्ष-स्तरीय JSON:API document का हिस्सा होता है। ये ऑब्जेक्ट्स हमेशा विनिर्देशन द्वारा परिभाषित कुंजियों (जैसे jsonapi, data, included या errors) के अंतर्गत स्थित होते हैं।

Resource Object

किसी entity का JSON ऑब्जेक्ट के रूप में निरूपण। इसे “resource” से भ्रमित नहीं होना चाहिए। यह एप्लिकेशन के डेटा के साथ एक-से-एक सामंजस्य रखता है।

Attributes Object

वह JSON ऑब्जेक्ट जो उस resource object के बारे में जानकारी दर्शाता है जिसमें वह परिभाषित है। Attributes में कोई भी वैध JSON मान हो सकता है। Drupal की भाषा में, यह ऑब्जेक्ट उन सभी entity फ़ील्ड मानों का प्रतिनिधित्व करता है जो entity references नहीं हैं।

Relationships Object (बहुवचन)

वह JSON ऑब्जेक्ट जो उस resource object से अन्य resource objects के लिए संदर्भों को रखता है जिसमें वह परिभाषित है। इसमें कई सदस्य होते हैं जो relationship (एकवचन) objects होते हैं। Drupal की भाषा में, यह ऑब्जेक्ट सभी entity reference फ़ील्ड मानों का प्रतिनिधित्व करता है।

Relationship Object (एकवचन)

वह JSON ऑब्जेक्ट जो उस resource object से अन्य resource objects के लिए संदर्भों का प्रतिनिधित्व करता है जिसमें वह परिभाषित है। इसमें resource identifier objects होते हैं, जिनमें से प्रत्येक किसी अन्य resource object के साथ एक एकल relationship का प्रतिनिधित्व करता है। Drupal की भाषा में, यह ऑब्जेक्ट किसी एक entity reference फ़ील्ड का प्रतिनिधित्व करता है।

Resource Identifier Object

एक बहुत सरल JSON ऑब्जेक्ट जो एक resource object से दूसरे तक के संबंध का प्रतिनिधित्व करता है। इसे “resource object” से भ्रमित नहीं होना चाहिए। इसमें केवल type और id कुंजी होती हैं, और उस संबंध के बारे में जानकारी रखने हेतु एक वैकल्पिक meta कुंजी हो सकती है। विशेषतः, इसमें links सदस्य नहीं होता।

यह “resource linkage” प्रदान करता है जो किसी compound document में HTTP क्लाइंट को relationship objects को included सदस्य में संदर्भित resource object(s) से सहसंबद्ध (correlate) करने देता है।

Links Object

वह JSON ऑब्जेक्ट जिसमें अन्य resources के लिए हाइपरलिंक्स होते हैं।

Error Object

वह JSON ऑब्जेक्ट जो किसी अनुरोध को प्रोसेस करते समय घटित त्रुटि का प्रतिनिधित्व करता है। ये अन्य बातों के साथ-साथ क्लाइंट त्रुटियाँ, वैधता (validation) त्रुटियाँ और सर्वर त्रुटियाँ दर्शा सकते हैं।

लेख स्रोत: Drupal Documentation.