शामिल करना (Includes)

संक्षेप (TL;DR): इस तरह की क्वेरी स्ट्रिंग का उपयोग करें ?include=field_comments.uid ताकि field_comments द्वारा संदर्भित सभी entities और उन entities पर uid द्वारा संदर्भित सभी entities शामिल की जा सकें!

JSON:API आपकी मदद करता है HTTP अनुरोधों को समाप्त करने में, जिससे आप यह निर्दिष्ट कर सकते हैं कि किन relationship paths को आप response document में शामिल करना चाहते हैं। कैसे?

एकल संसाधन प्राप्त करना

लेख प्राप्त करें

मान लें कि आपके पास एक लेख है जिसमें दो टिप्पणियाँ हैं और उन दोनों टिप्पणियों के लेखक एक ही हैं। बिना includes के सभी डेटा प्राप्त करने के लिए, आपको सबसे पहले इस तरह अनुरोध करना होगा: GET /jsonapi/node/article/some-random-uuid:

{
  "data": {
    "type": "node--article",
    "id": "some-random-uuid",
    "relationships": {
      "field_comments": {
        "links": {
          "related": {
            "href": "https://my.example.com/node/article/some-random-uuid/field_comments"
          }
        }
      }
    }
  }
}

टिप्पणियाँ प्राप्त करें

फिर आपको इस तरह अनुरोध करना होगा: GET /node/article/some-random-uuid/field_comments:

{
  "data": [{
    "type": "comment",
    "id": "one-random-uuid",
    "relationships": {
      "uid": {
        "links": {
          "related": {
            "href": "https://my.example.com/comment/one-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "comment",
    "id": "two-random-uuid",
    "relationships": {
      "uid": {
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }
}

उपयोगकर्ता प्राप्त करें

और फिर, आपको दो और अनुरोध करने होंगे: /comment/one-random-uuid/uid और /comment/two-random-uuid/uid। हम देख सकते हैं कि दूसरा अनुरोध पूरी तरह से अनावश्यक है क्योंकि हमारे उदाहरण में दोनों टिप्पणियों का लेखक एक ही है।

तो, includes कैसे मदद कर सकते हैं?

include का उपयोग करके सभी को एक साथ प्राप्त करें

यह आसान है! बस मूल अनुरोध URL में क्वेरी पैरामीटर जोड़कर, जिसमें उन relationship फ़ील्ड्स के नाम हों जिन्हें आप शामिल करना चाहते हैं, सर्वर आपके लिए सभी डेटा ढूँढ लेगा और उन्हें मूल response document में जोड़ देगा।

हमारे उदाहरण में, अनुरोध URL होगा: GET /jsonapi/node/article/some-random-uuid?include=field_comments.uid। दूसरे शब्दों में, आप कह रहे हैं "कृपया लेख पर field_comments फ़ील्ड के resource objects जोड़ें, फिर उन टिप्पणियों पर uid फ़ील्ड के resource objects भी जोड़ें जिन्हें यह संदर्भित करता है।" ये "relationship paths" जितने लंबे चाहें उतने हो सकते हैं, कोई सीमा नहीं है!

सर्वर से प्राप्त response document इस प्रकार होगा:

{
  "data": {
    "type": "node--article",
    "id": "some-random-uuid",
    "relationships": {
      "field_comments": {
        "data": [{
          "type": "comment",
          "id": "one-random-uuid",
        }, {
          "type": "comment",
          "id": "two-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/node/article/some-random-uuid/field_comments"
          }
        }
      }
    }
  },
  "included": [{
    "type": "comment",
    "id": "one-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "another-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/one-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "comment",
    "id": "another-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "one-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

क्या यह बढ़िया नहीं है? हमें केवल एक अनुरोध में सारा डेटा मिल गया! ध्यान दें कि उपयोगकर्ता resource object केवल एक बार शामिल किया गया है, भले ही इसका दो बार संदर्भ लिया गया हो। इससे प्रतिक्रिया का आकार कम हो जाता है। साथ ही, ध्यान दें कि अब प्रत्येक relationship object में एक data कुंजी है। यह आपको शामिल किए गए resource objects को उन resource objects से संबंधित करने देता है जिन्होंने उनका संदर्भ दिया।

include का उपयोग कब करें?

प्रतिक्रिया आकार की बात करें... इस उदाहरण में, हमने सभी संसाधनों को एक अनुरोध में प्राप्त करके समय बचाया। हालाँकि, कुछ परिस्थितियों में, संबंधित resource objects को शामिल करने से प्रतिक्रिया का आकार बहुत बड़ा हो सकता है और/या पहला बाइट आने का समय बहुत धीमा हो सकता है। ऐसी स्थिति में, फिर भी समानांतर में कई अनुरोध करना बेहतर हो सकता है।

संग्रह (collection) और संबंध (relationship) के लिए include

अंत में, include क्वेरी पैरामीटर collection और relationship resources पर भी समर्थित है! collections पर includes आपको कई अनुरोध बचा सकते हैं।

collection के लिए include का उदाहरण

collection के लिए include प्राप्त करने का अनुरोध कुछ इस तरह दिख सकता है: GET /jsonapi/node/article?include=uid। यहाँ included डेटा से अलग दिखाया गया है (object के बजाय array) जैसा नीचे दिखाया गया है।

{
  "data": [{...}]
  "included": [{
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

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