मुख्य अवधारणाएँ

JSON:API में कई अवधारणाएँ हैं, जिनमें से सभी यहाँ प्रलेखित नहीं हैं। हालाँकि, इस मॉड्यूल के उपयोगकर्ताओं को उत्पादक बनने के लिए विनिर्देशन की सभी अवधारणाओं को पूरी तरह से समझने की ज़रूरत नहीं है। यदि आप यह गहराई से समझना चाहते हैं कि JSON:API के दस्तावेज़ कैसे संरचित होते हैं, मॉड्यूल किसी कार्य को एक तरीके से क्यों करता है, या बस मॉड्यूल के डिज़ाइन के बारे में अधिक जानना चाहते हैं, तो पाठकों को jsonapi.org पर विनिर्देशन पढ़ने की सलाह दी जाती है।

दस्तावेज़ संरचना

JSON:API इस बात को लेकर बहुत स्पष्ट है कि JSON दस्तावेज़ कैसे संरचित होने चाहिए और हर अनुरोध/प्रतिक्रिया बॉडी में कौन सी जानकारी होनी चाहिए।

हर अनुरोध/प्रतिक्रिया बॉडी एकल JSON ऑब्जेक्ट के अंतर्गत होनी चाहिए।

{
   // आपका डेटा यहाँ...
}

डेटा, या किसी संसाधन से संबंधित जानकारी, इस शीर्ष-स्तरीय ऑब्जेक्ट के data “member” के अंतर्गत रहना ज़रूरी है। एक “member” बस JSON ऑब्जेक्ट में एक पूर्व-परिभाषित कुंजी है। data सदस्य या तो ऑब्जेक्ट ({}) या ऐरे ([]) हो सकता है। जब आप कोई संसाधन बनाते या अपडेट करते हैं, तो यह हमेशा एक ऑब्जेक्ट ({}) होगा, जो एक एकल आइटम का प्रतिनिधित्व करता है। केवल जब आप एक “कलेक्शन” (एक से अधिक संसाधनों का समूह) प्राप्त करते हैं, तब यह प्रॉपर्टी ऐरे होगी।

{
  "data": {
    // आपका संसाधन डेटा यहाँ होगा।
  }
}

अन्य शीर्ष-स्तरीय सदस्य हैं: errors, meta, links, और included। इनमें से included का उपयोग सबसे अधिक होता है, लेकिन इस पर बाद में दस्तावेज़ में चर्चा की जाएगी।

शीर्ष-स्तरीय संरचना पर अधिक जानकारी के लिए, आप विनिर्देशन देख सकते हैं।

data और included सदस्यों के भीतर “resource objects” या “resource identifier objects” होते हैं। “Resource objects” संसाधनों (entities) की सामग्री का प्रतिनिधित्व करते हैं। “Resource identifier objects” डेटाबेस में foreign keys की तरह होते हैं; वे किसी संसाधन को पहचानते हैं लेकिन उसके फ़ील्ड्स शामिल नहीं करते। Drupal की भाषा में, एक resource object आमतौर पर एक entity (जैसे node, taxonomy term, या user) का JSON प्रतिनिधित्व होता है। वहीं, resource identifier में केवल इतना ही डेटा होता है कि entity को लोड किया जा सके—आपके पास उसका type और ID होता है और कुछ नहीं।

हर resource object में दो सदस्य ज़रूर होने चाहिए: type और id। इसका एकमात्र अपवाद तब है जब आप नई entity बना रहे हों—इस स्थिति में id छोड़ा जा सकता है ताकि Drupal नई entity के लिए ID उत्पन्न कर सके। हालाँकि, क्लाइंट एप्लिकेशन भी entity बनाते समय UUID प्रदान कर सकता है। JSON:API में सभी ID UUID होती हैं।

type सदस्य हमेशा आवश्यक है। इसका मान entity type नाम और bundle से लिया जाता है, जहाँ लागू हो। entity resource का type हमेशा इस पैटर्न का पालन करता है: entity_type--bundle। उदाहरण के लिए, core article और basic page node types क्रमशः node--article और node--page के रूप में दर्शाए जाएँगे।

इस प्रकार, बिना किसी आवश्यक प्रॉपर्टी या फ़ील्ड वाली entity के लिए, कोई निम्नलिखित JSON से नई entity बना सकता है:

{
  "data": {
    "type": "node--my-bundle",
  }
}

हालाँकि यह बहुत उपयोगी नहीं होगा। हमें entity के लिए वास्तविक मान शामिल करने होंगे। इसके लिए, JSON:API के पास मान रखने के लिए दो सदस्य हैं: attributes और relationships। attributes संसाधन से संबंधित विशिष्ट मान स्टोर करते हैं। relationships वे मान होते हैं जो सिस्टम में किसी अन्य संसाधन से संबंधित होते हैं। Drupal में, relationships आमतौर पर entity reference के मान का प्रतिनिधित्व करते हैं। उदाहरण के लिए, article bundle पर uid प्रॉपर्टी। ऐसा इसलिए क्योंकि uid उस user की entity reference है जिसने article लिखा है। attributes और relationships वाला दस्तावेज़ इस प्रकार दिख सकता है:

{
  "data": {
    "type": "node--my-bundle",
    "id": "2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e",
    "attributes": {
      "title": "An Example"
    },
    "relationships": {
      "uid": {
        "data": {
          "type": "user--user",
          "id": "53bb14cc-544a-4cf2-88e8-e9cdd0b6948f"
        }
      }
    }
  }
}

जैसा कि आप देख सकते हैं, uid प्रॉपर्टी relationships सदस्य के अंतर्गत है। मुख्य संसाधन की तरह, इसमें भी type और id सदस्य हैं क्योंकि यह एक अलग और विशिष्ट संसाधन है।

ध्यान दें कि uid में कोई attributes या relationships नहीं हैं। ऐसा इसलिए है क्योंकि JSON:API किसी relationship की सामग्री शामिल नहीं करता जब तक कि उसे विशेष query पैरामीटर include के माध्यम से स्पष्ट रूप से न कहा जाए। इस पर बाद में दस्तावेज़ में चर्चा होगी (देखें “Fetching resources (GET)”).

Resource objects की संरचना पर अधिक जानकारी के लिए, आप विनिर्देशन देख सकते हैं।

§ “वर्चुअल” Resource Identifiers

कुछ परिस्थितियों में, Drupal किसी relationship को ऐसे संसाधन (entity reference) की ओर इंगित करने की अनुमति देता है जो डेटाबेस में संग्रहीत नहीं होता और इसलिए JSON:API के माध्यम से उपलब्ध नहीं होता। “वर्चुअल” resource identifier विभिन्न परिस्थितियों का संकेत दे सकता है, लेकिन यह हमेशा किसी ऐसे संसाधन से संबंधित होगा जिसे नहीं पाया जा सकता।

Drupal Core में ‘virtual’ resource identifier का उपयोग और अर्थ

Drupal core में इस विशेष मामले का सबसे उल्लेखनीय उदाहरण taxonomy term का parent फ़ील्ड है। यह relationship फ़ील्ड एक “वर्चुअल” taxonomy term संसाधन के लिए resource identifier रख सकता है। इस स्थिति में, “वर्चुअल” resource identifier <root> taxonomy term को पहचानता है। इसका अर्थ है कि संबंधित term अपनी vocabulary के शीर्ष स्तर पर है।

निम्नलिखित प्रतिक्रिया दस्तावेज़ को एक काल्पनिक taxonomy term के उदाहरण के रूप में देखें:

{
  "data": {
    "type": "taxonomy_term--tags",
    "id": "2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e",
    "attributes": {
      "name": "Politics"
    },
    "relationships": {
      "parent": {
        "data": [
          {
            "id": "virtual",
            "type": "taxonomy_term--tags",
            "meta": {
              "links": {
                "help": {
                  "href": "https://www.drupal.org/docs/8/modules/json-api/core-concepts#virtual",
                  "meta": {
                    "about": "‘virtual’ resource identifier का उपयोग और अर्थ।"
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}

ध्यान दें कि इस Term की parent relationship (एक entity reference फ़ील्ड) में resource identifier ऑब्जेक्ट है जहाँ id UUID नहीं है, यह "virtual" है। यह आवश्यक है क्योंकि शीर्ष-स्तर या root-स्तर Term के पास एक unstored <root> term (target_id = 0) होता है जो उसका parent है।

क्यों?

क्योंकि root term संग्रहीत नहीं है और एक Term के एक से अधिक parent हो सकते हैं, तो मुख्य प्रश्न है: हम कैसे अंतर करें कि कोई Term:

• केवल Term 3 को parent के रूप में रखता है ([3])?
• इस unstored root Term और Term 3 दोनों को parent के रूप में रखता है ([0, 3])?

उत्तर यह है कि यदि JSON:API unstored root term 0 को छोड़ दे और "virtual" ID का उपयोग न करे, तो इन दोनों मामलों में अंतर करना संभव नहीं होगा!

§ “Missing” Resource Identifiers

Drupal उन संबंधों को “clean up” नहीं करता जो हटाए गए संसाधनों की ओर इशारा करते हैं (entity reference फ़ील्ड्स जिनमें हटाए गए entities के रेफरेंस हैं)। दूसरे शब्दों में: Drupal “dangling” relationships (entity references) को उसी रूप में छोड़ देता है।

जब JSON:API ऐसे dangling relationships पाता है, तो यह “missing” resource identifier का उपयोग करता है।

Drupal Core में ‘missing’ resource identifier का उपयोग और अर्थ

‘virtual’ resource identifier के उदाहरण से जारी रखते हुए: taxonomy term का parent फ़ील्ड। कल्पना करें कि कोई विशेष taxonomy term पहले “Belgium” taxonomy term का parent था, लेकिन अब “Belgium” taxonomy term संसाधन मौजूद नहीं है — शायद इसलिए कि Belgium देश अस्तित्व में नहीं रहा। इस स्थिति में, यह relationship फ़ील्ड एक “missing” taxonomy term संसाधन का resource identifier रखेगा।

निम्नलिखित प्रतिक्रिया दस्तावेज़ को एक काल्पनिक taxonomy term के उदाहरण के रूप में देखें:

{
  "data": {
    "type": "taxonomy_term--tags",
    "id": "2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e",
    "attributes": {
      "name": "Politics"
    },
    "relationships": {
      "parent": {
        "data": [
          {
            "id": "missing",
            "type": "unknown",
            "meta": {
              "links": {
                "help": {
                  "href": "https://www.drupal.org/docs/8/modules/json-api/core-concepts#missing",
                  "meta": {
                    "about": "‘missing’ resource identifier का उपयोग और अर्थ।"
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}

ध्यान दें कि इस Term की parent relationship (एक entity reference फ़ील्ड) में resource identifier ऑब्जेक्ट है जहाँ id UUID नहीं है, यह "missing" है। इतना ही नहीं, इसका type भी unknown है (क्योंकि Drupal संदर्भित entity के bundle को संग्रहीत नहीं करता, केवल entity type को संग्रहीत करता है, इसलिए JSON:API resource type नाम निर्धारित करना असंभव है)।

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