http - रीस्ट एपीआई पैच या पुट




rest http-put (3)

आरईएसटी में आर संसाधन के लिए खड़ा है

(जो सच नहीं है, क्योंकि यह प्रतिनिधि के लिए है, लेकिन आरईएसटी में संसाधनों के महत्व को याद रखना एक अच्छी चाल है)।

PUT /groups/api/v1/groups/{group id}/status/activate : आप "सक्रिय" अपडेट नहीं कर रहे हैं। एक "सक्रिय" एक बात नहीं है, यह एक क्रिया है। क्रिया कभी अच्छे संसाधन नहीं होते हैं। अंगूठे का नियम: यदि क्रिया, एक क्रिया, यूआरएल में है, तो शायद यह रीस्टफुल नहीं है

इसके बजाय आप क्या कर रहे हैं? या तो आप किसी समूह पर सक्रियण को "जोड़ना", "निकालना" या "अपडेट करना" कर रहे हैं, या यदि आप चाहें: किसी समूह पर "स्थिति" - संसाधन को जोड़ना। व्यक्तिगत रूप से, मैं "सक्रियण" का उपयोग करता हूं क्योंकि वे "स्थिति" अवधारणा से कम अस्पष्ट हैं: एक स्थिति बनाना संदिग्ध है, एक सक्रियण बनाना नहीं है।

  • POST /groups/{group id}/activation बनाता है (या सृजन का अनुरोध करता है)।
  • PATCH /groups/{group id}/activation मौजूदा सक्रियण के कुछ विवरण अपडेट करता है। चूंकि एक समूह में केवल एक सक्रियण है, हम जानते हैं कि हम किस सक्रियण-संसाधन का जिक्र कर रहे हैं।
  • PUT /groups/{group id}/activation पुराने सक्रियण को सम्मिलित करता है या बदलता है। चूंकि एक समूह में केवल एक सक्रियण है, हम जानते हैं कि हम किस सक्रियण-संसाधन का जिक्र कर रहे हैं।
  • DELETE /groups/{group id}/activation रद्द कर देगा, या सक्रियण को हटा देगा।

यह पैटर्न तब उपयोगी होता है जब किसी समूह के "सक्रियण" के दुष्प्रभाव होते हैं, जैसे भुगतान किए जा रहे हैं, मेल भेजे जा रहे हैं और इसी तरह। केवल पोस्ट और पैच के ऐसे दुष्प्रभाव हो सकते हैं। जब उदाहरण के लिए सक्रियण को हटाने की आवश्यकता है, तो मेल पर उपयोगकर्ताओं को सूचित करें, DELETE सही विकल्प नहीं है; उस स्थिति में आप शायद एक निष्क्रिय संसाधन बनाना चाहते हैं: POST /groups/{group_id}/deactivation

इन दिशानिर्देशों का पालन करना एक अच्छा विचार है, क्योंकि यह मानक अनुबंध आपके ग्राहकों के लिए यह स्पष्ट करता है, और ग्राहक और आप के बीच सभी प्रॉक्सी और परतें, जब यह पुनः प्रयास करना सुरक्षित होता है, और जब नहीं। आइए मान लें कि क्लाइंट फ्लैकी वाईफ़ाई के साथ कहीं है, और इसका उपयोगकर्ता "निष्क्रिय" पर क्लिक करता है, जो एक DELETE ट्रिगर करता है: यदि यह विफल हो जाता है, तो क्लाइंट बस पुनः प्रयास कर सकता है, जब तक कि यह 404, 200 या किसी और चीज को संभालने में सक्षम न हो। लेकिन अगर यह POST to deactivation एक POST to deactivation ट्रिगर करता है तो यह पुनः प्रयास करने के लिए नहीं जानता है: POST इसका तात्पर्य है।
किसी भी ग्राहक के पास अब एक अनुबंध है, जो बाद में, 42 ईमेल "आपके समूह को निष्क्रिय कर दिया गया है" भेजने के खिलाफ सुरक्षा करेगा, क्योंकि इसकी HTTP-लाइब्रेरी बैकएंड को कॉल को फिर से ले रही है।

एक विशेषता को अपडेट करना: पैच का उपयोग करें

PATCH /groups/{group id}

यदि आप एक विशेषता को अपडेट करना चाहते हैं। जैसे "स्थिति" समूह पर एक विशेषता हो सकती है जिसे सेट किया जा सकता है। "स्थिति" जैसी विशेषता अक्सर मूल्यों की श्वेतसूची तक सीमित होने के लिए एक अच्छा उम्मीदवार होता है। उदाहरण कुछ अपरिभाषित जेएसओएन-योजना का उपयोग करते हैं:

PATCH /groups/{group id} { "attributes": { "status": "active" } }
response: 200 OK

PATCH /groups/{group id} { "attributes": { "status": "deleted" } }
response: 406 Not Acceptable

साइड इफेक्ट्स के बिना संसाधन को प्रतिस्थापित करना PUT का उपयोग करें।

PUT /groups/{group id}

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

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

PUT /groups/{group id} { "attributes": { "status": "active" } }
response: 406 Not Acceptable

PUT /groups/{group id} { "attributes": { "name": .... etc. "status": "active" } }
response: 201 Created or 200 OK, depending on whether we made a new one.

एक बहुत ही महत्वपूर्ण आवश्यकता यह है कि PUT बेवकूफ है: यदि आपको समूह को अपडेट करते समय साइड इफेक्ट्स की आवश्यकता होती है (या एक सक्रियण बदलना), तो आपको PATCH उपयोग करना चाहिए। इसलिए, जब अद्यतन परिणाम जैसे मेल भेजना, PUT उपयोग न करें।

मैं निम्नलिखित परिदृश्य के लिए उचित विधि के साथ अपने बाकी एंडपॉइंट को डिज़ाइन करना चाहता हूं।

एक समूह है प्रत्येक समूह की स्थिति होती है। समूह को व्यवस्थापक द्वारा सक्रिय या निष्क्रिय किया जा सकता है।

क्या मुझे अपना अंत बिंदु डिजाइन करना चाहिए

PUT /groups/api/v1/groups/{group id}/status/activate

या

PATCH /groups/api/v1/groups/{group id}

with request body like 
{action:activate|deactivate}

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

/groups/api/groups/{group id}/status

संशोधन के लिए पैच पर इस दृष्टिकोण का नकारात्मक पक्ष यह है कि आप समूह की एक से अधिक संपत्तियों पर पारस्परिक रूप से और लेन-देन में परिवर्तन नहीं कर पाएंगे। यदि लेनदेन संबंधी परिवर्तन महत्वपूर्ण हैं तो पैच का उपयोग करें।

यदि आप समूह के उप-संसाधन के रूप में स्थिति का पर्दाफाश करने का निर्णय लेते हैं तो यह समूह के प्रतिनिधित्व में एक लिंक होना चाहिए। उदाहरण के लिए यदि एजेंट समूह 123 प्राप्त करता है और एक्सएमएल स्वीकार करता है तो प्रतिक्रिया निकाय में निम्न शामिल हो सकते हैं:

<group id="123">
  <status>Active</status>
  <link rel="/linkrels/groups/status" uri="/groups/api/groups/123/status"/>
  ...
</group>

रेस्ट वास्तुकला शैली की अनुप्रयोग स्थिति की स्थिति के इंजन के रूप में हाइपर्मियाडिया को पूरा करने के लिए एक हाइपरलिंक की आवश्यकता होती है।


मैं पैच का उपयोग करने की अनुशंसा करता हूं, क्योंकि आपके संसाधन 'समूह' में कई गुण हैं लेकिन इस मामले में, आप केवल सक्रियण फ़ील्ड (आंशिक संशोधन) अपडेट कर रहे हैं

आरएफसी 578 9 के अनुसार ( https://tools.ietf.org/html/rfc5789 )

मौजूदा HTTP PUT विधि केवल दस्तावेज़ के पूर्ण प्रतिस्थापन की अनुमति देती है। मौजूदा प्रस्ताव को संशोधित करने के लिए यह प्रस्ताव एक नई HTTP विधि, पैच जोड़ता है।

इसके अलावा, अधिक जानकारी में,

पुट और पैच अनुरोधों के बीच का अंतर सर्वर के संसाधन को संशोधित करने के लिए संलग्न इकाई को संसाधित करने के तरीके में दिखाई देता है
अनुरोध-यूआरआई द्वारा पहचाना गया। एक पुट अनुरोध में, संलग्न इकाई को संग्रहीत संसाधन का एक संशोधित संस्करण माना जाता है
मूल सर्वर, और क्लाइंट संग्रहीत संस्करण का अनुरोध कर रहा है
प्रतिस्थापित किया। पैच के साथ, हालांकि, संलग्न इकाई में निर्देशों का एक सेट होता है जो बताता है कि वर्तमान में संसाधन किस प्रकार रहता है
मूल सर्वर को एक नया संस्करण बनाने के लिए संशोधित किया जाना चाहिए। पैच विधि अनुरोध-यूआरआई द्वारा पहचाने गए संसाधन को प्रभावित करती है, और यह
अन्य संसाधनों पर दुष्प्रभाव भी हो सकते हैं; यानी, नए संसाधन
ए के आवेदन से बनाया जा सकता है, या मौजूदा संशोधित किया जा सकता है
PATCH।

[आरएफसी 2616], धारा 9.1 द्वारा परिभाषित पैच न तो सुरक्षित और न ही बेवकूफ है।

ग्राहकों को चुनने की जरूरत है कि पुट के बजाय पैच का उपयोग कब करें। के लिये
उदाहरण के लिए, यदि पैच दस्तावेज़ का आकार आकार के मुकाबले बड़ा है
नया संसाधन डेटा जिसका उपयोग PUT में किया जाएगा, तो यह हो सकता है
पैच के बजाय PUT का उपयोग करने के लिए भावना। POST की तुलना में और भी मुश्किल है, क्योंकि POST का व्यापक रूप से भिन्न तरीकों से उपयोग किया जा सकता है और कर सकते हैं
यदि सर्वर चुनता है तो पुट और पैच-जैसे ऑपरेशन शामिल करें। अगर
ऑपरेशन अनुरोध-यूआरआई द्वारा अनुमानित संसाधन में पहचाने गए संसाधन को संशोधित नहीं करता है, पोस्ट को पैच के बजाय माना जाना चाहिए
या पुट।

पैच के लिए प्रतिक्रिया कोड है

204 प्रतिक्रिया कोड का उपयोग किया जाता है क्योंकि प्रतिक्रिया में संदेश निकाय नहीं होता है (जो 200 कोड के साथ प्रतिक्रिया होगी)। ध्यान दें कि अन्य सफलता कोड भी इस्तेमाल किए जा सकते हैं।

यह भी देखें: //restcookbook.com/HTTP%20Methods/patch/

चेतावनी: पैच को लागू करने वाला एक एपीआई परमाणु रूप से पैच करना चाहिए। यह संभव नहीं है कि जीईटी द्वारा अनुरोध किए जाने पर संसाधन आधे-पैच किए जाएं।





http-patch