प्रदर्शन सुझाव

इस दस्तावेज़ में, ऐप्लिकेशन की परफ़ॉर्मेंस को बेहतर बनाने के लिए इस्तेमाल की जा सकने वाली कुछ तकनीकों के बारे में बताया गया है. कुछ मामलों में, बताए गए आइडिया को समझाने के लिए, अन्य एपीआई या सामान्य एपीआई के उदाहरणों का इस्तेमाल किया जाता है. हालांकि, यही सिद्धांत Gmail API पर भी लागू होते हैं.

gzip का इस्तेमाल करके कंप्रेस करना

हर अनुरोध के लिए ज़रूरी बैंडविड्थ को कम करने का एक आसान और सुविधाजनक तरीका है, gzip कंप्रेशन को चालू करना. हालांकि, नतीजों को अनकंप्रेस करने के लिए, सीपीयू को ज़्यादा समय देना पड़ता है. हालांकि, नेटवर्क की लागत के साथ ट्रेड-ऑफ़ करने पर, यह तरीका आम तौर पर बहुत फ़ायदेमंद होता है.

gzip-encoded रिस्पॉन्स पाने के लिए, आपको ये दो काम करने होंगे: Accept-Encoding हेडर सेट करें और अपने उपयोगकर्ता एजेंट में बदलाव करके, उसमें gzip स्ट्रिंग शामिल करें. यहां gzip कंप्रेशन को चालू करने के लिए, सही तरीके से बनाए गए एचटीटीपी हेडर का उदाहरण दिया गया है:

Accept-Encoding: gzip
User-Agent: my program (gzip)

कुछ संसाधनों के साथ काम करना

एपीआई कॉल की परफ़ॉर्मेंस को बेहतर बनाने का एक और तरीका यह है कि सिर्फ़ उस डेटा को भेजा और पाया जाए जिसमें आपकी दिलचस्पी है. इससे आपका ऐप्लिकेशन, गैर-ज़रूरी फ़ील्ड को ट्रांसफ़र, पार्स, और सेव करने से बचता है. इसलिए, यह नेटवर्क, सीपीयू, और मेमोरी जैसे संसाधनों का ज़्यादा बेहतर तरीके से इस्तेमाल कर सकता है.

आंशिक अनुरोध दो तरह के होते हैं:

• आंशिक जवाब: ऐसा अनुरोध जिसमें यह तय किया जाता है कि जवाब में कौनसे फ़ील्ड शामिल करने हैं. इसके लिए, fields अनुरोध पैरामीटर का इस्तेमाल करें.
• पैच: यह अपडेट करने का ऐसा अनुरोध होता है जिसमें सिर्फ़ वे फ़ील्ड भेजे जाते हैं जिनमें आपको बदलाव करना है. इसके लिए, PATCH एचटीटीपी वर्ब का इस्तेमाल करें.

आंशिक अनुरोध करने के बारे में ज़्यादा जानकारी, यहां दिए गए सेक्शन में दी गई है.

अधूरे जवाब

डिफ़ॉल्ट रूप से, सर्वर अनुरोधों को प्रोसेस करने के बाद, किसी संसाधन का पूरा डेटा वापस भेजता है. बेहतर परफ़ॉर्मेंस के लिए, सर्वर से सिर्फ़ वे फ़ील्ड भेजने के लिए कहा जा सकता है जिनकी आपको ज़रूरत है. इसके बजाय, आपको अधूरा जवाब मिलेगा.

कुछ हिस्से का जवाब पाने का अनुरोध करने के लिए, fields अनुरोध पैरामीटर का इस्तेमाल करके वे फ़ील्ड बताएं जो आपको वापस चाहिए. इस पैरामीटर का इस्तेमाल, ऐसे किसी भी अनुरोध के साथ किया जा सकता है जिससे जवाब का डेटा मिलता है.

ध्यान दें कि fields पैरामीटर का असर सिर्फ़ जवाब के डेटा पर पड़ता है. अगर आपको कोई डेटा भेजना है, तो इस पैरामीटर का उस पर कोई असर नहीं पड़ता. संसाधनों में बदलाव करते समय भेजे जाने वाले डेटा की मात्रा को कम करने के लिए, patch अनुरोध का इस्तेमाल करें.

उदाहरण

इस उदाहरण में, सामान्य (काल्पनिक) "Demo" API के साथ fields पैरामीटर का इस्तेमाल दिखाया गया है.

सामान्य अनुरोध: इस एचटीटीपी GET अनुरोध में fields पैरामीटर शामिल नहीं है. साथ ही, यह पूरा संसाधन दिखाता है.

https://www.googleapis.com/demo/v1

पूरे संसाधन का जवाब: पूरे संसाधन के डेटा में ये फ़ील्ड शामिल होते हैं. साथ ही, इसमें कई अन्य फ़ील्ड भी शामिल होते हैं जिन्हें छोटा करने के लिए हटा दिया गया है.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

आंशिक जवाब का अनुरोध: इस संसाधन के लिए किए गए इस अनुरोध में, fields पैरामीटर का इस्तेमाल किया गया है. इससे, जवाब में मिलने वाले डेटा की मात्रा काफ़ी कम हो जाती है.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

आंशिक जवाब: ऊपर दिए गए अनुरोध के जवाब में, सर्वर सिर्फ़ तरह की जानकारी भेजता है. साथ ही, आइटम का छोटा किया गया ऐसा कलेक्शन भेजता है जिसमें हर आइटम में सिर्फ़ एचटीएमएल टाइटल और लंबाई की जानकारी शामिल होती है.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

ध्यान दें कि रिस्पॉन्स एक JSON ऑब्जेक्ट होता है. इसमें सिर्फ़ चुने गए फ़ील्ड और उनके पैरंट ऑब्जेक्ट शामिल होते हैं.

इसके बाद, fields पैरामीटर को फ़ॉर्मैट करने के तरीके के बारे में जानकारी दी गई है. इसके बाद, इस बारे में ज़्यादा जानकारी दी गई है कि रिस्पॉन्स में क्या-क्या शामिल होता है.

फ़ील्ड पैरामीटर के सिंटैक्स के बारे में खास जानकारी

fields अनुरोध के पैरामीटर की वैल्यू का फ़ॉर्मैट, XPath सिंटैक्स पर आधारित होता है. यहां दिए गए सिंटैक्स का इस्तेमाल किया जा सकता है. इसके बारे में यहां बताया गया है. साथ ही, ज़्यादा उदाहरण यहां दिए गए हैं.

• एक से ज़्यादा फ़ील्ड चुनने के लिए, कॉमा-सेपरेटेड लिस्ट का इस्तेमाल करें.
• a/b का इस्तेमाल करके, a फ़ील्ड में नेस्ट किए गए b फ़ील्ड को चुनें. a/b/c का इस्तेमाल करके, b फ़ील्ड में नेस्ट किए गए c फ़ील्ड को चुनें.
  

  अपवाद: "data" रैपर का इस्तेमाल करने वाले एपीआई रिस्पॉन्स के लिए, जहां रिस्पॉन्स को data ऑब्जेक्ट में नेस्ट किया गया है और वह data: { ... } जैसा दिखता है, वहां fields स्पेसिफ़िकेशन में "data" शामिल न करें. data/a/b जैसे फ़ील्ड स्पेसिफ़िकेशन वाले डेटा ऑब्जेक्ट को शामिल करने पर गड़बड़ी होती है. इसके बजाय, सिर्फ़ fields स्पेसिफ़िकेशन का इस्तेमाल करें. जैसे, a/b.

• ऐरे या ऑब्जेक्ट के सब-फ़ील्ड के किसी खास सेट का अनुरोध करने के लिए, सब-चुनने वाले का इस्तेमाल करें. इसके लिए, एक्सप्रेशन को कोष्ठक "( )" में रखें.

  उदाहरण के लिए: fields=items(id,author/email), items ऐरे में मौजूद हर एलिमेंट के लिए सिर्फ़ आइटम आईडी और लेखक का ईमेल दिखाता है. एक सब-फ़ील्ड भी तय किया जा सकता है, जहां fields=items(id) का मतलब fields=items/id से है.

• ज़रूरत पड़ने पर, फ़ील्ड चुनने के लिए वाइल्डकार्ड का इस्तेमाल करें.

  उदाहरण के लिए: fields=items/pagemap/*, पेजमैप में मौजूद सभी ऑब्जेक्ट चुनता है.

फ़ील्ड पैरामीटर इस्तेमाल करने के अन्य उदाहरण

यहां दिए गए उदाहरणों में बताया गया है कि fields पैरामीटर की वैल्यू, जवाब पर कैसे असर डालती है.

ध्यान दें: सभी क्वेरी पैरामीटर वैल्यू की तरह, fields पैरामीटर वैल्यू को भी कोड में बदलना ज़रूरी है. इस दस्तावेज़ में दिए गए उदाहरणों में एन्कोडिंग को शामिल नहीं किया गया है, ताकि उन्हें आसानी से पढ़ा जा सके.

उन फ़ील्ड की पहचान करें जिनकी वैल्यू आपको चाहिए या फ़ील्ड चुनें.

अनुरोध पैरामीटर की वैल्यू, कॉमा से अलग किए गए फ़ील्ड की सूची होती है. साथ ही, हर फ़ील्ड को जवाब के रूट के हिसाब से तय किया जाता है.fields इसलिए, अगर list ऑपरेशन किया जा रहा है, तो जवाब एक कलेक्शन होता है. इसमें आम तौर पर संसाधनों की एक ऐरे शामिल होती है. अगर आपको ऐसी कार्रवाई करनी है जिससे सिर्फ़ एक संसाधन मिलता है, तो फ़ील्ड उस संसाधन के हिसाब से तय किए जाते हैं. अगर चुना गया फ़ील्ड, किसी ऐरे का हिस्सा है या कोई ऐरे है, तो सर्वर, ऐरे में मौजूद सभी एलिमेंट का चुना गया हिस्सा दिखाता है.

यहां कलेक्शन-लेवल के कुछ उदाहरण दिए गए हैं:

उदाहरण	असर
items	यह फ़ंक्शन, items कलेक्शन में मौजूद सभी एलिमेंट दिखाता है. इनमें हर एलिमेंट के सभी फ़ील्ड शामिल होते हैं, लेकिन कोई अन्य फ़ील्ड शामिल नहीं होता.
etag,items	etag फ़ील्ड और items कलेक्शन में मौजूद सभी एलिमेंट दिखाता है.
items/title	यह फ़ंक्शन, items ऐरे में मौजूद सभी एलिमेंट के लिए सिर्फ़ title फ़ील्ड दिखाता है. जब भी कोई नेस्ट किया गया फ़ील्ड वापस भेजा जाता है, तो रिस्पॉन्स में पैरंट ऑब्जेक्ट शामिल होते हैं. पैरंट फ़ील्ड में कोई अन्य चाइल्ड फ़ील्ड शामिल नहीं होता, जब तक कि उसे साफ़ तौर पर नहीं चुना जाता.
context/facets/label	यह facets कलेक्शन के सभी सदस्यों के लिए, सिर्फ़ label फ़ील्ड दिखाता है. यह फ़ील्ड, context ऑब्जेक्ट में नेस्ट किया गया है.
items/pagemap/*/title	आइटम कलेक्शन में मौजूद हर एलिमेंट के लिए, सिर्फ़ title फ़ील्ड (अगर मौजूद है) दिखाता है. यह फ़ील्ड, pagemap के सभी चाइल्ड ऑब्जेक्ट का होता है.

यहां संसाधन-लेवल के कुछ उदाहरण दिए गए हैं:

उदाहरण	असर
title	अनुरोध किए गए संसाधन का title फ़ील्ड दिखाता है.
author/uri	यह अनुरोध किए गए संसाधन में मौजूद author ऑब्जेक्ट का uri सब-फ़ील्ड दिखाता है.
links/*/href	यह फ़ंक्शन, href के सभी चाइल्ड ऑब्जेक्ट के href फ़ील्ड की वैल्यू दिखाता है.links

सब-सिलेक्शन का इस्तेमाल करके, सिर्फ़ खास फ़ील्ड के कुछ हिस्सों का अनुरोध करें.

डिफ़ॉल्ट रूप से, अगर आपके अनुरोध में कुछ फ़ील्ड के बारे में बताया गया है, तो सर्वर ऑब्जेक्ट या अरे एलिमेंट को पूरी तरह से दिखाता है. आपके पास ऐसा जवाब देने का विकल्प होता है जिसमें सिर्फ़ कुछ सब-फ़ील्ड शामिल हों. इसके लिए, "( )" सब-सिलेक्शन सिंटैक्स का इस्तेमाल करें. उदाहरण के लिए, यहां दिया गया तरीका अपनाएं.

उदाहरण	असर
items(title,author/uri)	यह आइटम ऐरे में मौजूद हर एलिमेंट के लिए, सिर्फ़ title और लेखक के uri की वैल्यू दिखाता है.

अधूरे जवाबों को मैनेज करना

जब सर्वर, fields क्वेरी पैरामीटर वाले किसी मान्य अनुरोध को प्रोसेस कर लेता है, तब वह अनुरोध किए गए डेटा के साथ एचटीटीपी 200 OK स्टेटस कोड वापस भेजता है. अगर fields क्वेरी पैरामीटर में कोई गड़बड़ी है या यह अमान्य है, तो सर्वर एचटीटीपी 400 Bad Request स्टेटस कोड दिखाता है. साथ ही, गड़बड़ी का एक मैसेज दिखाता है, जिसमें उपयोगकर्ता को बताया जाता है कि फ़ील्ड चुनने में क्या गड़बड़ी हुई है. उदाहरण के लिए, "Invalid field selection a/b".

यहां अधूरे जवाब का उदाहरण दिया गया है, जिसे ऊपर परिचय वाले सेक्शन में दिखाया गया है. अनुरोध में fields पैरामीटर का इस्तेमाल किया जाता है. इससे यह तय किया जाता है कि किन फ़ील्ड को वापस भेजना है.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

अधूरा जवाब ऐसा दिखता है:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

ध्यान दें: ऐसे एपीआई के लिए जो डेटा पेज पर बांटने के लिए क्वेरी पैरामीटर (उदाहरण के लिए, maxResults और nextPageToken) का इस्तेमाल करते हैं, उन पैरामीटर का इस्तेमाल करके हर क्वेरी के नतीजों को कम करें, ताकि उन्हें मैनेज किया जा सके. ऐसा न करने पर, आंशिक जवाब से मिलने वाले परफ़ॉर्मेंस फ़ायदे नहीं मिल पाएंगे.

पैच (आंशिक अपडेट)

संसाधनों में बदलाव करते समय, गैर-ज़रूरी डेटा भेजने से भी बचा जा सकता है. अगर आपको सिर्फ़ उन फ़ील्ड के लिए अपडेट किया गया डेटा भेजना है जिनमें बदलाव किया जा रहा है, तो HTTP PATCH वर्ब का इस्तेमाल करें. इस दस्तावेज़ में बताए गए पैच से जुड़े सेमेंटिक, पुराने GData के आंशिक अपडेट के मुकाबले अलग (और आसान) हैं.

नीचे दिए गए छोटे उदाहरण में बताया गया है कि पैच का इस्तेमाल करने से, छोटा अपडेट करने के लिए आपको कितना कम डेटा भेजना पड़ता है.

उदाहरण

इस उदाहरण में, "डेमो" नाम की जेनेरिक (काल्पनिक) एपीआई संसाधन के सिर्फ़ टाइटल को अपडेट करने के लिए, एक सामान्य पैच अनुरोध दिखाया गया है. इस संसाधन में टिप्पणी, विशेषताओं का सेट, स्थिति, और कई अन्य फ़ील्ड भी हैं. हालांकि, इस अनुरोध में सिर्फ़ title फ़ील्ड भेजा जाता है, क्योंकि सिर्फ़ इसी फ़ील्ड में बदलाव किया जा रहा है:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

जवाब:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

सर्वर, अपडेट किए गए संसाधन की पूरी जानकारी के साथ 200 OK स्टेटस कोड दिखाता है. पैच के अनुरोध में सिर्फ़ title फ़ील्ड को शामिल किया गया था. इसलिए, सिर्फ़ यही वैल्यू पहले से अलग है.

ध्यान दें: अगर आपने पैच के साथ आंशिक जवाब fields पैरामीटर का इस्तेमाल किया है, तो अपडेट के अनुरोधों को और भी ज़्यादा असरदार बनाया जा सकता है. पैच अनुरोध से सिर्फ़ अनुरोध का साइज़ कम होता है. अधूरा जवाब मिलने से, जवाब का साइज़ कम हो जाता है. इसलिए, दोनों दिशाओं में भेजे जाने वाले डेटा की मात्रा को कम करने के लिए, fields पैरामीटर के साथ पैच अनुरोध का इस्तेमाल करें.

पैच अनुरोध का सिमैंटिक

पैच अनुरोध के मुख्य हिस्से में, सिर्फ़ वे संसाधन फ़ील्ड शामिल होते हैं जिनमें आपको बदलाव करना है. किसी फ़ील्ड को तय करते समय, आपको उसके पैरंट ऑब्जेक्ट को शामिल करना होगा. ठीक उसी तरह जैसे कुछ हिस्से के जवाब में पैरंट ऑब्जेक्ट शामिल होते हैं. अगर कोई पैरंट ऑब्जेक्ट मौजूद है, तो भेजा गया बदला हुआ डेटा, पैरंट ऑब्जेक्ट के डेटा में मर्ज हो जाता है.

• जोड़ें: अगर आपको ऐसा फ़ील्ड जोड़ना है जो पहले से मौजूद नहीं है, तो नया फ़ील्ड और उसकी वैल्यू डालें.
• बदलें: किसी मौजूदा फ़ील्ड की वैल्यू बदलने के लिए, फ़ील्ड तय करें और उसे नई वैल्यू पर सेट करें.
  
• मिटाना: किसी फ़ील्ड को मिटाने के लिए, फ़ील्ड तय करें और उसे null पर सेट करें. उदाहरण के लिए, "comment": null. अगर कोई ऑब्जेक्ट बदला जा सकता है, तो उसे null पर सेट करके, पूरे ऑब्जेक्ट को भी मिटाया जा सकता है. अगर Java API क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो Data.NULL_STRING का इस्तेमाल करें. ज़्यादा जानकारी के लिए, JSON null देखें.

ऐरे के बारे में जानकारी: ऐरे वाले पैच अनुरोध, मौजूदा ऐरे को आपकी दी गई ऐरे से बदल देते हैं. किसी ऐरे में आइटम को अलग-अलग करके न तो बदला जा सकता है, न जोड़ा जा सकता है, और न ही मिटाया जा सकता है.

पढ़ें-बदलें-लिखें साइकल में पैच का इस्तेमाल करना

यह एक अच्छा तरीका है कि आप उस डेटा का कुछ हिस्सा वापस पाएं जिसमें आपको बदलाव करना है. यह उन संसाधनों के लिए खास तौर पर ज़रूरी है जो ETags का इस्तेमाल करते हैं. ऐसा इसलिए, क्योंकि संसाधन को अपडेट करने के लिए, आपको If-Match एचटीटीपी हेडर में मौजूदा ETag वैल्यू देनी होगी. डेटा मिलने के बाद, आपको जिन वैल्यू में बदलाव करना है उनमें बदलाव करें. इसके बाद, पैच अनुरोध के साथ बदलाव किया गया डेटा वापस भेजें. यहां एक उदाहरण दिया गया है, जिसमें यह माना गया है कि डेमो संसाधन, ईटैग का इस्तेमाल करता है:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

यह अधूरा जवाब है:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

नीचे दिया गया पैच अनुरोध, उस जवाब पर आधारित है. नीचे दिए गए उदाहरण में दिखाया गया है कि यह fields पैरामीटर का इस्तेमाल करके, पैच रिस्पॉन्स में मिले डेटा को सीमित करता है:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

सर्वर, 200 OK एचटीटीपी स्टेटस कोड के साथ जवाब देता है. साथ ही, अपडेट किए गए संसाधन का कुछ हिस्सा दिखाता है:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

सीधे तौर पर पैच अनुरोध बनाना

कुछ पैच अनुरोधों के लिए, आपको उन्हें उस डेटा के आधार पर बनाना होगा जिसे आपने पहले वापस पाया था. उदाहरण के लिए, अगर आपको किसी ऐरे में कोई आइटम जोड़ना है और आपको मौजूदा ऐरे एलिमेंट में से किसी को भी नहीं हटाना है, तो आपको पहले मौजूदा डेटा पाना होगा. इसी तरह, अगर कोई एपीआई ETags का इस्तेमाल करता है, तो संसाधन को अपडेट करने के लिए, आपको अपने अनुरोध के साथ पिछली ETag वैल्यू भेजनी होगी.

ध्यान दें: ईटैग का इस्तेमाल करते समय, किसी पैच को लागू करने के लिए "If-Match: *" एचटीटीपी हेडर का इस्तेमाल किया जा सकता है.  ऐसा करने पर, आपको लिखने से पहले पढ़ने की ज़रूरत नहीं होती.

हालांकि, अन्य स्थितियों में मौजूदा डेटा को पहले से हासिल किए बिना, सीधे तौर पर पैच अनुरोध बनाया जा सकता है. उदाहरण के लिए, पैच का अनुरोध आसानी से सेट अप किया जा सकता है. इससे किसी फ़ील्ड को नई वैल्यू पर अपडेट किया जा सकता है या नया फ़ील्ड जोड़ा जा सकता है. उदाहरण के लिए:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

इस अनुरोध के साथ, अगर टिप्पणी वाले फ़ील्ड में कोई मौजूदा वैल्यू है, तो नई वैल्यू उसे बदल देती है. अगर कोई वैल्यू नहीं है, तो नई वैल्यू सेट हो जाती है. इसी तरह, अगर वॉल्यूम की कोई विशेषता थी, तो उसकी वैल्यू बदल दी जाती है. अगर नहीं थी, तो उसे बना दिया जाता है. अगर सटीक जानकारी वाला फ़ील्ड सेट है, तो उसे हटा दिया जाता है.

पैच के जवाब को मैनेज करना

मान्य पैच अनुरोध को प्रोसेस करने के बाद, एपीआई 200 OK एचटीटीपी रिस्पॉन्स कोड दिखाता है. साथ ही, बदले गए संसाधन का पूरा ब्यौरा भी दिखाता है. अगर एपीआई, ETags का इस्तेमाल करता है, तो पैच अनुरोध को प्रोसेस करने के बाद सर्वर, ETag की वैल्यू अपडेट करता है. ऐसा ही PUT के साथ भी होता है.

पैच अनुरोध, पूरे संसाधन का प्रतिनिधित्व दिखाता है. हालांकि, अगर आपको इससे मिलने वाले डेटा की मात्रा कम करनी है, तो fields पैरामीटर का इस्तेमाल करें.

अगर पैच के अनुरोध से संसाधन की ऐसी नई स्थिति बनती है जो सिंटैक्टिक या सिमैंटिक तौर पर अमान्य है, तो सर्वर 400 Bad Request या 422 Unprocessable Entity एचटीटीपी स्टेटस कोड दिखाता है. साथ ही, संसाधन की स्थिति में कोई बदलाव नहीं होता. उदाहरण के लिए, अगर किसी ज़रूरी फ़ील्ड की वैल्यू मिटाने की कोशिश की जाती है, तो सर्वर एक गड़बड़ी दिखाता है.

PATCH HTTP वर्ब काम न करने पर, दूसरा नोटेशन

अगर आपका फ़ायरवॉल, एचटीटीपी PATCH अनुरोधों की अनुमति नहीं देता है, तो एचटीटीपी POST अनुरोध करें और ओवरराइड हेडर को PATCH पर सेट करें. ऐसा नीचे दिए गए तरीके से करें:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

पैच और अपडेट में अंतर

अपडेट के अनुरोध के लिए, एचटीटीपी PUT वर्ब का इस्तेमाल करके डेटा भेजते समय, आपको सिर्फ़ वे फ़ील्ड भेजने होते हैं जो ज़रूरी या वैकल्पिक होते हैं. अगर सर्वर की ओर से सेट किए गए फ़ील्ड के लिए वैल्यू भेजी जाती हैं, तो उन्हें अनदेखा कर दिया जाता है. हालांकि, यह आंशिक अपडेट करने का एक और तरीका लग सकता है, लेकिन इस तरीके की कुछ सीमाएं हैं. एचटीटीपी PUT वर्ब का इस्तेमाल करने वाले अपडेट के लिए, ज़रूरी पैरामीटर न देने पर अनुरोध पूरा नहीं होता. साथ ही, वैकल्पिक पैरामीटर न देने पर, पहले से सेट किया गया डेटा मिट जाता है.

इसलिए, पैच का इस्तेमाल करना ज़्यादा सुरक्षित होता है. सिर्फ़ उन फ़ील्ड के लिए डेटा दें जिनमें आपको बदलाव करना है. जिन फ़ील्ड के लिए डेटा नहीं दिया जाता है उन्हें खाली नहीं किया जाता. इस नियम का सिर्फ़ एक अपवाद है. यह दोहराए जाने वाले एलिमेंट या ऐरे पर लागू होता है: अगर आपने इनमें से किसी को भी शामिल नहीं किया है, तो ये पहले जैसे ही रहेंगे. अगर आपने इनमें से किसी को भी शामिल किया है, तो पूरा सेट आपके दिए गए सेट से बदल दिया जाएगा.