Blogger JSON API: परफ़ॉर्मेंस के बारे में सुझाव

अहम जानकारी: हम 30 सितंबर, 2024 से, v2.0 JSON API के साथ काम करना बंद कर देंगे. काम करते रहने के लिए, अपने उन ऐप्लिकेशन को अपडेट करें जो v2.0 JSON API का इस्तेमाल करके, एपीआई के नए वर्शन पर काम करते हैं. सबसे नए वर्शन के लिए, बाईं ओर के नेविगेशन बार में दिए गए लिंक का इस्तेमाल करें.

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

gzip की मदद से कंप्रेस करना

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

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

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

आंशिक संसाधनों के साथ काम करना

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

अधूरे अनुरोध दो तरह के होते हैं:

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

कुछ हद तक अनुरोध करने से जुड़ी ज़्यादा जानकारी नीचे दिए गए सेक्शन में दी गई है.

अधूरे जवाब

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

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

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

उदाहरण

इस उदाहरण में, जेनरिक (काल्पनिक) "Demo" एपीआई के साथ 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 अनुरोध के पैरामीटर की वैल्यू का फ़ॉर्मैट, आम तौर पर एक्सएमएल सिंटैक्स पर आधारित होता है. यहां इस्तेमाल किए जा सकने वाले सिंटैक्स के बारे में खास जानकारी दी गई है. साथ ही, कुछ और उदाहरण यहां दिए गए हैं.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

उदाहरण	असर
title	यह फ़ंक्शन, अनुरोध किए गए संसाधन का title फ़ील्ड दिखाता है.
author/uri	यह फ़ंक्शन, अनुरोध किए गए संसाधन में author ऑब्जेक्ट का uri सब-फ़ील्ड दिखाता है.
links/*/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) के लिए क्वेरी पैरामीटर के साथ काम करते हैं, उन पैरामीटर का इस्तेमाल करें, ताकि हर क्वेरी के नतीजों को मैनेज किए जा सकने वाले साइज़ तक कम किया जा सके. ऐसा न करने पर, हो सकता है कि अधूरे जवाब देने पर परफ़ॉर्मेंस अच्छा न हो.

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

संसाधनों में बदलाव करते समय बेवजह का डेटा भेजने से भी बचा जा सकता है. सिर्फ़ उन फ़ील्ड के लिए अपडेट किया गया डेटा भेजने के लिए जिन्हें बदला जा रहा है, एचटीटीपी 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 देखें.

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

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

आपको जिस डेटा में बदलाव करना है उसके साथ आंशिक जवाब पाने से शुरुआत करना फ़ायदेमंद हो सकता है. यह खास तौर पर, ETag का इस्तेमाल करने वाले संसाधनों के लिए ज़रूरी है, क्योंकि संसाधन को अपडेट करने के लिए, आपको If-Match एचटीटीपी हेडर में मौजूदा ETag वैल्यू देनी होगी. डेटा मिलने के बाद, उन वैल्यू में बदलाव किया जा सकता है जिन्हें बदलना है. साथ ही, बदलाव किए गए पार्शियल प्रज़ेंटेशन को पैच अनुरोध के साथ वापस भेजा जा सकता है. यहां एक उदाहरण दिया गया है, जिसमें माना जाता है कि डेमो रिसॉर्स, 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. */
  }
}

सीधे पैच अनुरोध तैयार करना

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

ध्यान दें: जब 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 एचटीटीपी रिस्पॉन्स कोड दिखाता है. अगर एपीआई, ETag का इस्तेमाल करता है, तो सर्वर PUT के साथ भी ठीक तरह से ETag वैल्यू को अपडेट करता है. ऐसा तब होता है, जब यह पैच के अनुरोध को प्रोसेस करता है.

पैच अनुरोध की मदद से, पूरा संसाधन दिखाया जाता है. ऐसा तब तक होता है, जब तक fields पैरामीटर का इस्तेमाल करके, लौटाए जाने वाले डेटा की मात्रा को कम नहीं किया जाता.

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

PATCH HTTP क्रिया समर्थित न होने पर वैकल्पिक संकेतन

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

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

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

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

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