web services आरईएसटी को समझना: क्रियाएं, त्रुटि कोड, और प्रमाणीकरण




web-services rest (8)

मैं अपने PHP- आधारित वेब अनुप्रयोगों, डेटाबेस और सीएमएस में डिफ़ॉल्ट कार्यों के आसपास एपीआई लपेटने का एक तरीका ढूंढ रहा हूं।

मैंने चारों ओर देखा है और कई "कंकाल" ढांचे को पाया है। मेरे प्रश्न में दिए गए उत्तरों के अलावा, Tonic , मुझे एक आरईएसटी फ्रेमवर्क पसंद है क्योंकि यह बहुत हल्का है।

मुझे अपनी सादगी के लिए सबसे अच्छा आरईएसटी पसंद है, और इसके आधार पर एक एपीआई आर्किटेक्चर बनाना चाहते हैं। मैं अपने सिद्धांतों को बुनियादी सिद्धांतों के चारों ओर लाने की कोशिश कर रहा हूं और अभी तक इसे पूरी तरह समझ नहीं पाया है। इसलिए, कई सवाल हैं।

1. क्या मैं इसे सही समझ रहा हूँ?

मान लें कि मेरे पास संसाधन "उपयोगकर्ता" है। मैं इस तरह के कई यूआरआई स्थापित कर सकता था:

/api/users     when called with GET, lists users
/api/users     when called with POST, creates user record
/api/users/1   when called with GET, shows user record
               when called with PUT, updates user record
               when called with DELETE, deletes user record

क्या यह अब तक एक विश्वसनीय वास्तुकला का सही प्रतिनिधित्व है?

2. मुझे और क्रियाओं की आवश्यकता है

निर्माण, अद्यतन और हटाएं सिद्धांत में पर्याप्त हो सकती हैं, लेकिन व्यवहार में मुझे बहुत अधिक क्रियाओं की आवश्यकता होगी। मुझे एहसास है कि ये चीजें हैं जिन्हें अद्यतन अनुरोध में एम्बेड किया जा सकता है, लेकिन वे विशिष्ट कार्य हैं जिनके पास विशिष्ट रिटर्न कोड हो सकते हैं और मैं उन्हें सभी को एक क्रिया में फेंकना नहीं चाहता हूं।

कुछ जो उपयोगकर्ता के उदाहरण में दिमाग में आते हैं वे हैं:

activate_login
deactivate_login
change_password
add_credit

मैं एक विश्वसनीय यूआरएल आर्किटेक्चर में ऐसे कार्यों को कैसे व्यक्त करूं?

मेरा वृत्ति एक यूआरएल जैसे जीईटी कॉल करना होगा

/api/users/1/activate_login 

और एक स्थिति कोड वापस उम्मीद है।

हालांकि, HTTP क्रियाओं का उपयोग करने के विचार से विचलित हो जाता है। तुम क्या सोचते हो?

3. त्रुटि संदेश और कोड कैसे वापस करें

आरईएसटी की सुंदरता का एक बड़ा हिस्सा मानक HTTP विधियों के उपयोग से उत्पन्न होता है। एक त्रुटि पर, मैं एक 3x, 4xx या 5xx त्रुटि स्थिति कोड के साथ एक शीर्षलेख उत्सर्जित करता हूं। विस्तृत त्रुटि विवरण के लिए, मैं शरीर का उपयोग कर सकता हूं (दाएं?)। अब तक सब ठीक है। लेकिन एक स्वामित्व त्रुटि कोड संचारित करने का तरीका क्या होगा जो गलत होने का वर्णन करने में अधिक विस्तृत है (उदाहरण के लिए "डेटाबेस से कनेक्ट करने में विफल", या "डेटाबेस लॉगिन गलत")? अगर मैं इसे संदेश के साथ शरीर में डालता हूं, तो मुझे इसे बाद में पार्स करना होगा। क्या इस तरह की चीज़ के लिए एक मानक शीर्षलेख है?

4. प्रमाणीकरण कैसे करें

  • आरईएसटी सिद्धांतों के बाद एपीआई कुंजी आधारित प्रमाणीकरण कैसा दिखता है?
  • आरईएसटी क्लाइंट को प्रमाणित करते समय सत्रों का उपयोग करने के खिलाफ मजबूत अंक हैं, इसके अलावा यह आरईएसटी सिद्धांत का एक स्पष्ट उल्लंघन है? :) (यहां केवल आधे मजाक कर रहे हैं, सत्र आधारित प्रमाणीकरण मेरे मौजूदा बुनियादी ढांचे के साथ अच्छी तरह से खेलेंगे।)

  1. पोस्ट का उपयोग करें जब आप नहीं जानते कि नया संसाधन यूआरआई कैसा दिखता है (आप नया उपयोगकर्ता बनाते हैं, एप्लिकेशन नए उपयोगकर्ता को आईडी निर्दिष्ट करेगा), संसाधनों को अद्यतन करने या बनाने के लिए PUT जिसे आप जानते हैं कि उन्हें कैसे प्रदर्शित किया जा रहा है (उदाहरण : PUT /myfiles/thisismynewfile.txt)
  2. संदेश निकाय में त्रुटि विवरण वापस करें
  3. आप HTTP प्रमाणीकरण का उपयोग कर सकते हैं (यदि यह पर्याप्त है) वेब सेवाएं stateles होना चाहिए

आपके द्वारा बताए गए उदाहरणों के लिए मैं निम्नलिखित का उपयोग करूंगा:

activate_login

POST /users/1/activation

deactivate_login

DELETE /users/1/activation

पासवर्ड बदलें

PUT /passwords (यह मानता है कि उपयोगकर्ता प्रमाणीकृत है)

क्रेडिट जोड़ने

POST /credits (यह मानता है कि उपयोगकर्ता प्रमाणित है)

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

DELETE /users/1.xml

आप एक्सएमएल में प्रतिक्रिया वापस भेज देंगे, यह JSON आदि के लिए भी सच होगा ...

प्रमाणीकरण के लिए आपको http प्रमाणीकरण का उपयोग करना चाहिए।


सीधे शब्दों में कहें, आप इसे पूरी तरह पिछड़ा कर रहे हैं।

आपको इसका उपयोग नहीं करना चाहिए कि आप किन URL का उपयोग कर रहे हैं। एक बार जब आप यह तय कर लेंगे कि आपके सिस्टम के लिए कौन से संसाधन आवश्यक हैं और आप उन संसाधनों का प्रतिनिधित्व कैसे करेंगे, और संसाधनों और एप्लिकेशन स्थिति के बीच बातचीत कैसे करेंगे, तो URL प्रभावी रूप से "नि: शुल्क" आ जाएंगे।

रॉय फील्डिंग को उद्धृत करने के लिए

एक आरईएसटी एपीआई को संसाधनों का प्रतिनिधित्व करने और आवेदन राज्य चलाने के लिए उपयोग किए जाने वाले मीडिया प्रकार (या) को मौजूदा मानक मीडिया प्रकारों के लिए विस्तारित संबंध नाम और / या हाइपरटेक्स्ट-सक्षम मार्क-अप को परिभाषित करने में लगभग सभी वर्णनात्मक प्रयासों को खर्च करना चाहिए। मीडिया के प्रकार के लिए प्रसंस्करण नियमों के दायरे में (और, ज्यादातर मामलों में, पहले से ही मौजूदा मीडिया प्रकारों द्वारा परिभाषित) के दायरे में यूआरआई के ब्याज पर किस तरीके का उपयोग किया जाना चाहिए, इसका वर्णन करने के लिए खर्च किए गए किसी भी प्रयास का वर्णन किया गया है। [यहां विफलता का तात्पर्य है कि ऑफ-ऑफ-बैंड जानकारी हाइपरटेक्स्ट की बजाय बातचीत चला रही है।]

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

ईमानदार होने के लिए, कई यूआरआई और कुछ जीईटी और पुट्स और पोस्ट्स का एक गुच्छा देखते हैं और लगता है कि आरईएसटी आसान है। आरईएसटी आसान नहीं है। HTTP पर आरपीसी आसान है, HTTP पेलोड के माध्यम से पीछे और पीछे डेटा के चलते ब्लॉब्स आसान है। आरईएसटी, हालांकि, उससे परे चला जाता है। आरईएसटी प्रोटोकॉल अज्ञेयवादी है। HTTP आरईएसटी सिस्टम के लिए बहुत लोकप्रिय और उपयुक्त है।

आरईएसटी मीडिया प्रकारों, उनकी परिभाषाओं, और कैसे हाइपरटेक्स्ट (लिंक, प्रभावी ढंग से) के माध्यम से उन संसाधनों के लिए उपलब्ध कार्यों को चलाता है।

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

दोनों दृष्टिकोणों में उनकी जगह है, मुझे लगता है कि एक्सएचटीएमएल उन परिदृश्यों में बहुत अच्छी तरह से काम कर रहा है जो मानव संचालित और मशीन संचालित वेब दोनों को ओवरलैप करते हैं, जबकि पूर्व, अधिक विशिष्ट डेटा प्रकार मैं मशीन इंटरैक्शन के लिए मशीन को बेहतर ढंग से सुविधाजनक महसूस करता हूं। मुझे लगता है कि कमोडिटी प्रारूपों का उत्थान सामग्री बातचीत को संभावित रूप से कठिन बना सकता है। "एप्लिकेशन / एक्सएमएल + आपका संसाधन" मीडिया प्रकार के रूप में "एप्लिकेशन / एक्सएचटीएमएल + एक्सएमएल" की तुलना में अधिक विशिष्ट है, क्योंकि बाद वाले कई पेलोड पर लागू हो सकते हैं जो कि मशीन क्लाइंट वास्तव में रुचि रखते हैं या नहीं भी हो सकता है, न ही यह आत्मनिरीक्षण के बिना निर्धारित करें।

हालांकि, एक्सएचटीएमएल मानव वेब में बहुत अच्छी तरह से काम करता है (स्पष्ट रूप से) जहां वेब ब्राउज़र और प्रतिपादन बहुत महत्वपूर्ण है।

आप आवेदन आपको उन निर्णयों में मार्गदर्शन करेंगे।

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

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

उदाहरण के लिए, आपके पास हो सकता है:

<link href="http://example.com/users" rel="users" type="application/xml+usercollection"/>
<link href="http://example.com/users?search" rel="search" type="application/xml+usersearchcriteria"/>

आपका दस्तावेज़ "उपयोगकर्ता" नामक रिले फ़ील्ड और "एप्लिकेशन / एक्सएमएल + यूज़र" के मीडिया प्रकार के बारे में बात करेगा।

ये लिंक अनावश्यक प्रतीत हो सकते हैं, वे सभी एक ही यूआरआई से बात कर रहे हैं, बहुत ज्यादा। लेकिन वे नहीं हैं।

ऐसा इसलिए है क्योंकि "उपयोगकर्ता" संबंध के लिए, यह लिंक उपयोगकर्ताओं के संग्रह के बारे में बात कर रहा है, और आप संग्रह के साथ काम करने के लिए वर्दी इंटरफ़ेस का उपयोग कर सकते हैं (उन सभी को पुनर्प्राप्त करने के लिए प्राप्त करें, उन सभी को हटाने के लिए हटाएं, आदि)

यदि आप इस यूआरएल पर पोस्ट करते हैं, तो आपको "एप्लिकेशन / एक्सएमएल + यूजरकोलेक्शन" दस्तावेज पास करना होगा, जिसमें शायद दस्तावेज़ में केवल एक ही उपयोगकर्ता उदाहरण होगा, ताकि आप उपयोगकर्ता को जोड़ सकें, या नहीं, शायद, कई को जोड़ने के लिए एक बार। शायद आपके दस्तावेज़ीकरण से पता चलता है कि आप संग्रह के बजाय, केवल एक उपयोगकर्ता प्रकार को पास कर सकते हैं।

आप खोज कर सकते हैं कि खोज करने के लिए एप्लिकेशन को क्या चाहिए, जैसा कि "खोज" लिंक द्वारा परिभाषित किया गया है और यह मध्यस्थता है। खोज मीडिया प्रकार के लिए प्रलेखन आपको बताएगा कि यह कैसे व्यवहार करता है, और परिणामों के रूप में क्या उम्मीद करनी है।

यहां ले लिया गया, हालांकि, यूआरआई स्वयं मूल रूप से महत्वहीन हैं। आवेदन यूआरआई के नियंत्रण में है, ग्राहकों को नहीं। कुछ 'प्रवेश बिंदु' से परे, आपके ग्राहकों को अपने काम के लिए आवेदन द्वारा प्रदान किए गए यूआरआई पर भरोसा करना चाहिए।

ग्राहक को यह जानने की जरूरत है कि मीडिया प्रकारों में हेरफेर और व्याख्या कैसे करें, लेकिन जहां यह जाता है, परवाह करने की आवश्यकता नहीं है।

ये दो लिंक एक ग्राहक आंखों में अर्थात् समान हैं:

<link href="http://example.com/users?search" rel="search" type="application/xml+usersearchcriteria"/>
<link href="http://example.com/AW163FH87SGV" rel="search" type="application/xml+usersearchcriteria"/>

तो, अपने संसाधनों पर ध्यान केंद्रित करें। आवेदन में उनके राज्य संक्रमण पर ध्यान केंद्रित करें और यह कैसे सर्वोत्तम रूप से हासिल किया जाता है।


1. आपको अपने संसाधनों को डिजाइन करने के बारे में सही विचार है, आईएमएचओ। मैं एक चीज़ नहीं बदलूंगा।

2. अधिक क्रियाओं के साथ HTTP का विस्तार करने की कोशिश करने के बजाय, बुनियादी HTTP विधियों और संसाधनों के संदर्भ में आपके प्रस्तावित क्रियाओं को कम किया जा सकता है। उदाहरण के लिए, एक activate_login क्रिया के बजाय, आप संसाधनों को सेट कर सकते हैं जैसे: /api/users/1/login/active जो एक साधारण बूलियन है। लॉगिन को सक्रिय करने के लिए, बस वहां एक दस्तावेज़ PUT जो 'सत्य' या 1 या जो कुछ भी कहता है। निष्क्रिय करने के लिए, वहां एक दस्तावेज़ PUT जो खाली है या 0 या झूठा कहता है।

इसी प्रकार, पासवर्ड बदलने या सेट करने के लिए, बस PUT /api/users/1/password s /api/users/1/password को PUT

जब भी आपको कुछ जोड़ने की आवश्यकता होती है (क्रेडिट की तरह) POST एस के मामले में सोचते हैं। उदाहरण के लिए, आप किसी संसाधन के साथ /api/users/1/credits साथ एक संसाधन में POST कर सकते हैं जिसमें जोड़ने के लिए क्रेडिट की संख्या होती है। एक ही संसाधन पर एक PUT उपयोग मूल्य के बजाय मूल्य को ओवरराइट करने के लिए किया जा सकता है। शरीर में एक नकारात्मक संख्या के साथ एक POST जाएगा, और इसी तरह।

3. मैं बुनियादी HTTP स्टेटस कोड को विस्तारित करने के खिलाफ दृढ़ता से सलाह देता हूं। अगर आपको कोई ऐसी स्थिति नहीं मिलती जो आपकी स्थिति से बिल्कुल मेल खाती है, तो निकटतम को चुनें और प्रतिक्रिया विवरण में त्रुटि विवरण डालें। साथ ही, याद रखें कि HTTP शीर्षलेख एक्स्टेंसिबल हैं; आपका एप्लिकेशन आपको पसंद होने वाले सभी कस्टम शीर्षकों को परिभाषित कर सकता है। एक आवेदन जिसे मैंने काम किया, उदाहरण के लिए, कई परिस्थितियों में 404 Not Found । क्लाइंट को कारण निकाय के कारण प्रतिक्रिया निकाय बनाने के बजाय, हमने अभी एक नया हेडर जोड़ा, X-Status-Extended , जिसमें हमारे मालिकाना स्थिति कोड एक्सटेंशन शामिल थे। तो आप एक प्रतिक्रिया देख सकते हैं जैसे:

HTTP/1.1 404 Not Found    
X-Status-Extended: 404.3 More Specific Error Here

इस तरह एक वेब ब्राउज़र जैसे HTTP क्लाइंट को अभी भी पता चलेगा कि नियमित 404 कोड के साथ क्या करना है, और अधिक परिष्कृत HTTP क्लाइंट अधिक विशिष्ट जानकारी के लिए X-Status-Extended शीर्षलेख को देखने का चयन कर सकता है।

4. प्रमाणीकरण के लिए, यदि आप कर सकते हैं तो HTTP प्रमाणीकरण का उपयोग करने की सलाह देते हैं। लेकिन आईएमएचओ में कुकी-आधारित प्रमाणीकरण का उपयोग करने में कुछ भी गलत नहीं है अगर यह आपके लिए आसान है।


Verbose, लेकिन http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html पर HTTP 1.1 विधि विनिर्देश से कॉपी किया गया

9.3 प्राप्त करें

जीईटी विधि का अर्थ है अनुरोध-यूआरआई द्वारा जो भी जानकारी (किसी इकाई के रूप में) को पुनर्प्राप्त किया जाता है। यदि अनुरोध-यूआरआई डेटा-उत्पादक प्रक्रिया को संदर्भित करता है, तो यह उत्पादित डेटा होता है जिसे प्रतिक्रिया में इकाई के रूप में वापस किया जाएगा, न कि प्रक्रिया के स्रोत पाठ, जब तक कि पाठ प्रक्रिया का आउटपुट न हो।

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

अनुरोध संदेश में रेंज हेडर फ़ील्ड शामिल होने पर जीईटी विधि का अर्थशास्त्र "आंशिक जीईटी" में बदल जाता है। आंशिक जीईटी अनुरोध करता है कि धारा 14.35 में वर्णित अनुसार इकाई का केवल एक हिस्सा स्थानांतरित किया जाए। आंशिक जीईटी विधि का उद्देश्य आंशिक रूप से पुनर्प्राप्त इकाइयों को क्लाइंट द्वारा पहले से किए गए डेटा को स्थानांतरित किए बिना अनावश्यक नेटवर्क उपयोग को कम करने के लिए किया गया है।

जीईटी अनुरोध की प्रतिक्रिया कैशबल है यदि केवल और अगर यह धारा 13 में वर्णित HTTP कैशिंग के लिए आवश्यकताओं को पूरा करती है।

प्रपत्रों के लिए उपयोग किए जाने पर सुरक्षा विचारों के लिए खंड 15.1.3 देखें।

9.5 पद

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

  - Annotation of existing resources;
  - Posting a message to a bulletin board, newsgroup, mailing list,
    or similar group of articles;
  - Providing a block of data, such as the result of submitting a
    form, to a data-handling process;
  - Extending a database through an append operation.

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

POST विधि द्वारा की गई क्रिया का परिणाम संसाधन में नहीं हो सकता है जिसे यूआरआई द्वारा पहचाना जा सकता है। इस मामले में, या तो 200 (ठीक) या 204 (कोई सामग्री नहीं) उचित प्रतिक्रिया स्थिति है, इस पर निर्भर करता है कि प्रतिक्रिया में एक इकाई शामिल है जो परिणाम का वर्णन करती है।

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

इस विधि के प्रतिसाद कैश करने योग्य नहीं हैं, जब तक कि प्रतिक्रिया में उपयुक्त कैश-कंट्रोल या हेडर फ़ील्ड समाप्त नहीं हो जाता है। हालांकि, 303 (अन्य देखें) प्रतिक्रिया का उपयोग उपयोगकर्ता एजेंट को कैशबल संसाधन पुनर्प्राप्त करने के लिए निर्देशित करने के लिए किया जा सकता है।

POST अनुरोधों को धारा 8.2 में निर्धारित संदेश संचरण आवश्यकताओं का पालन करना होगा।

सुरक्षा विचारों के लिए खंड 15.1.3 देखें।

9.6 पुट

पुट विधि अनुरोध करता है कि संलग्न इकाई आपूर्ति अनुरोध-यूआरआई के तहत संग्रहीत की जाए। यदि अनुरोध-यूआरआई पहले से मौजूद संसाधन को संदर्भित करता है, तो संलग्न इकाई को मूल सर्वर पर रहने वाले व्यक्ति के संशोधित संस्करण के रूप में माना जाना चाहिए। यदि अनुरोध-यूआरआई मौजूदा संसाधन को इंगित नहीं करता है, और यूआरआई अनुरोध करने वाले उपयोगकर्ता एजेंट द्वारा नए संसाधन के रूप में परिभाषित करने में सक्षम है, तो मूल सर्वर उस यूआरआई के साथ संसाधन बना सकता है। यदि कोई नया संसाधन बनाया गया है, तो मूल सर्वर को उपयोगकर्ता एजेंट को 201 (निर्मित) प्रतिक्रिया के माध्यम से सूचित करना होगा। If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request. If the resource could not be created or modified with the Request-URI, an appropriate error response SHOULD be given that reflects the nature of the problem. The recipient of the entity MUST NOT ignore any Content-* (eg Content-Range) headers that it does not understand or implement and MUST return a 501 (Not Implemented) response in such cases.

If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.

The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI,

it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request.

A single resource MAY be identified by many different URIs. For example, an article might have a URI for identifying "the current version" which is separate from the URI identifying each particular version. In this case, a PUT request on a general URI might result in several other URIs being defined by the origin server.

HTTP/1.1 does not define how a PUT method affects the state of an origin server.

PUT requests MUST obey the message transmission requirements set out in section 8.2.

Unless otherwise specified for a particular entity-header, the entity-headers in the PUT request SHOULD be applied to the resource created or modified by the PUT.

9.7 DELETE

The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden by human intervention (or other means) on the origin server. The client cannot be guaranteed that the operation has been carried out, even if the status code returned from the origin server indicates that the action has been completed successfully. However, the server SHOULD NOT indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location.

A successful response SHOULD be 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has not yet been enacted, or 204 (No Content) if the action has been enacted but the response does not include an entity.

If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.


About REST return codes: it is wrong to mix HTTP protocol codes and REST results.

However, I saw many implementations mixing them, and many developers may not agree with me.

HTTP return codes are related to the HTTP Request itself. A REST call is done using a Hypertext Transfer Protocol request and it works at a lower level than invoked REST method itself. REST is a concept/approach, and its output is a business/logical result, while HTTP result code is a transport one.

For example, returning "404 Not found" when you call /users/ is confuse, because it may mean:

  • URI is wrong (HTTP)
  • No users are found (REST)

"403 Forbidden/Access Denied" may mean:

  • Special permission needed. Browsers can handle it by asking the user/password. (HTTP)
  • Wrong access permissions configured on the server. (HTTP)
  • You need to be authenticated (REST)

And the list may continue with '500 Server error" (an Apache/Nginx HTTP thrown error or a business constraint error in REST) or other HTTP errors etc...

From the code, it's hard to understand what was the failure reason, a HTTP (transport) failure or a REST (logical) failure.

If the HTTP request physically was performed successfully it should always return 200 code, regardless is the record(s) found or not. Because URI resource is found and was handled by the http server. Yes, it may return an empty set. Is it possible to receive an empty web-page with 200 as http result, right?

Instead of this you may return 200 HTTP code and simply a JSON with an empty array/object, or to use a bool result/success flag to inform about the performed operation status.

Also, some internet providers may intercept your requests and return you a 404 http code. This does not means that your data are not found, but it's something wrong at transport level.

From Wiki :

In July 2004, the UK telecom provider BT Group deployed the Cleanfeed content blocking system, which returns a 404 error to any request for content identified as potentially illegal by the Internet Watch Foundation. Other ISPs return a HTTP 403 "forbidden" error in the same circumstances. The practice of employing fake 404 errors as a means to conceal censorship has also been reported in Thailand and Tunisia. In Tunisia, where censorship was severe before the 2011 revolution, people became aware of the nature of the fake 404 errors and created an imaginary character named "Ammar 404" who represents "the invisible censor".


पुनः 1 : यह अब तक ठीक दिखता है। "201 बनाया गया" स्थिति कोड के साथ POST के जवाब के हिस्से के रूप में "स्थान:" शीर्षलेख में नव निर्मित उपयोगकर्ता के यूआरआई को वापस याद रखना याद रखें।

पुनः 2 : जीईटी के माध्यम से सक्रियण एक बुरा विचार है, और यूआरआई में क्रिया सहित एक डिजाइन गंध है। आप एक जीईटी पर एक फॉर्म लौटने पर विचार करना चाह सकते हैं। एक वेब ऐप में, यह सबमिट बटन के साथ एक HTML फॉर्म होगा; एपीआई उपयोग के मामले में, आप एक ऐसे प्रतिनिधि को वापस करना चाहेंगे जिसमें खाते को सक्रिय करने के लिए पुष्ट करने के लिए यूआरआई शामिल है। बेशक आप इस यूआरआई को पोस्ट / उपयोगकर्ताओं पर प्रतिक्रिया में भी शामिल कर सकते हैं। PUT का उपयोग करके यह सुनिश्चित होगा कि आपका अनुरोध बेवकूफ है, यानी ग्राहक सफलतापूर्वक फिर से भेजा जा सकता है यदि ग्राहक सफलता के बारे में निश्चित नहीं है। आम तौर पर, इस बारे में सोचें कि आप अपने क्रियाओं को किस प्रकार संसाधनों में बदल सकते हैं ("क्रियाओं का संज्ञाकरण")। अपने आप से पूछें कि आपकी विशिष्ट कार्रवाई किस तरीके से गठबंधन है। जैसे change_password -> PUT; निष्क्रिय करें -> शायद हटाएं; add_credit -> संभवतः पोस्ट या पुट। क्लाइंट को उनके प्रतिनिधित्व में शामिल करके उपयुक्त यूआरआई को इंगित करें।

फिर 3. नए स्टेटस कोड का आविष्कार न करें, जब तक कि आपको विश्वास न हो कि वे इतने सामान्य हैं कि वे विश्व स्तर पर मानकीकृत होने की योग्यता रखते हैं। उपलब्ध सबसे उचित स्थिति कोड का उपयोग करने के लिए कड़ी मेहनत करें (आरएफसी 2616 में उन सभी के बारे में पढ़ें)। प्रतिक्रिया शरीर में अतिरिक्त जानकारी शामिल करें। यदि आप वास्तव में, वास्तव में सुनिश्चित हैं कि आप एक नया स्टेटस कोड आविष्कार करना चाहते हैं, तो फिर से सोचें; यदि आप अभी भी ऐसा मानते हैं, तो कम से कम सही श्रेणी (1xx -> ठीक है, 2xx -> सूचनात्मक, 3xx -> पुनर्निर्देशन; 4xx-> क्लाइंट त्रुटि, 5xx -> सर्वर त्रुटि) को सुनिश्चित करना सुनिश्चित करें। क्या मैंने उल्लेख किया कि नए स्टेटस कोड का आविष्कार करना एक बुरा विचार है?

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


मैंने इस सवाल को दो दिन देर से देखा, लेकिन मुझे लगता है कि मैं कुछ अंतर्दृष्टि जोड़ सकता हूं। मुझे उम्मीद है कि यह आपके अत्याधुनिक उद्यम के लिए सहायक हो सकता है।

प्वाइंट 1: क्या मैं इसे सही समझ रहा हूं?

आप सही समझ गए यह एक शानदार वास्तुकला का सही प्रतिनिधित्व है। आपको Wikipedia से निम्नलिखित मैट्रिक्स मिल सकते हैं जो आपके संज्ञाओं और क्रियाओं को परिभाषित करने में बहुत उपयोगी हैं:

संग्रह यूआरआई से निपटने पर: http://example.com/resources/

  • प्राप्त करें : संग्रह के सदस्यों की सूची बनाएं, आगे के नेविगेशन के लिए अपने सदस्य यूआरआई के साथ पूरा करें। उदाहरण के लिए, बिक्री के लिए सभी कारों की सूची।

  • PUT : मतलब "पूरे संग्रह को किसी अन्य संग्रह से प्रतिस्थापित करें" के रूप में परिभाषित किया गया है।

  • पोस्ट : संग्रह में एक नई प्रविष्टि बनाएं जहां आईडी संग्रह द्वारा स्वचालित रूप से असाइन की जाती है। बनाई गई आईडी को आमतौर पर इस ऑपरेशन द्वारा लौटाए गए डेटा के हिस्से के रूप में शामिल किया जाता है।

  • हटाएं : अर्थ "संपूर्ण संग्रह को हटाएं" के रूप में परिभाषित किया गया है।

सदस्य यूआरआई से निपटने पर: http://example.com/resources/7HOU57Y

  • प्राप्त करें : उपयुक्त MIME प्रकार में व्यक्त संग्रह के संबोधित सदस्य का प्रतिनिधित्व पुनर्प्राप्त करें

  • PUT : संग्रह के संबोधित सदस्य को अद्यतन करें या निर्दिष्ट आईडी के साथ बनाएं।

  • पोस्ट : संबोधित सदस्य को अपने अधिकार में एक संग्रह के रूप में मानता है और इसका एक नया अधीनस्थ बनाता है।

  • हटाएं : संग्रह के संबोधित सदस्य को हटाएं।

प्वाइंट 2: मुझे और क्रियाएं चाहिए

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

लॉगिन सक्रिय / निष्क्रिय करें : यदि आप एक नया सत्र बना रहे हैं, तो आप संसाधन के रूप में "सत्र" पर विचार करना चाहेंगे। नया सत्र बनाने के लिए, शरीर में क्रेडेंशियल्स के साथ http://example.com/sessions/ POST का उपयोग करें। इसे समाप्त करने के लिए इसे PUT या DELETE (हो सकता है कि आप सत्र इतिहास रखने का इरादा रखते हैं) का उपयोग http://example.com/sessions/SESSION_ID

पासवर्ड बदलें: इस बार संसाधन "उपयोगकर्ता" है। आपको शरीर में पुराने और नए पासवर्ड के साथ http://example.com/users/USER_ID एक PUT की आवश्यकता होगी। आप "उपयोगकर्ता" संसाधन पर काम कर रहे हैं, और एक परिवर्तन पासवर्ड बस एक अद्यतन अनुरोध है। यह एक संबंधपरक डेटाबेस में अद्यतन विवरण के समान है।

मेरा वृत्ति एक यूआरएल /api/users/1/activate_login जैसे यूआरएल को एक जीईटी कॉल करना होगा

यह एक बहुत ही मूल REST सिद्धांत के खिलाफ चला जाता है: HTTP क्रियाओं का सही उपयोग। किसी भी जीईटी अनुरोध को कभी भी कोई दुष्प्रभाव नहीं छोड़ना चाहिए।

उदाहरण के लिए, एक जीईटी अनुरोध डेटाबेस पर कभी भी सत्र नहीं बनाना चाहिए, एक नई सत्र आईडी के साथ कुकी वापस कर देना चाहिए, या सर्वर पर कोई अवशेष छोड़ना चाहिए। GET क्रिया डेटाबेस डेटाबेस में SELECT कथन की तरह है। याद रखें कि जीईटी क्रिया के साथ किसी भी अनुरोध की प्रतिक्रिया उसी पैरामीटर के साथ अनुरोध करते समय कैश-सक्षम होना चाहिए, जैसे कि जब आप एक स्थिर वेब पेज का अनुरोध करते हैं।

प्वाइंट 3: त्रुटि संदेश और कोड कैसे वापस करें

त्रुटि श्रेणियों के रूप में 4xx या 5xx HTTP स्थिति कोड पर विचार करें। आप शरीर में त्रुटि का विस्तार कर सकते हैं।

डेटाबेस से कनेक्ट करने में विफल: / गलत डेटाबेस लॉगिन : सामान्य रूप से आपको इन प्रकार की त्रुटियों के लिए 500 त्रुटि का उपयोग करना चाहिए। यह एक सर्वर-साइड त्रुटि है। ग्राहक ने कुछ भी गलत नहीं किया। 500 त्रुटियों को आम तौर पर "पुनः प्रयास करने योग्य" माना जाता है। यानी ग्राहक एक ही सटीक अनुरोध का पुनः प्रयास कर सकता है, और सर्वर की परेशानी का समाधान हो जाने के बाद इसे सफल होने की उम्मीद है। शरीर में विवरण निर्दिष्ट करें, ताकि ग्राहक हमें मनुष्यों को कुछ संदर्भ प्रदान कर सके।

त्रुटियों की दूसरी श्रेणी 4xx परिवार होगी, जो आम तौर पर इंगित करती है कि ग्राहक ने कुछ गलत किया था। विशेष रूप से, त्रुटियों की यह श्रेणी आम तौर पर क्लाइंट को इंगित करती है कि अनुरोध को फिर से प्रयास करने की कोई आवश्यकता नहीं है, क्योंकि यह स्थायी रूप से विफल रहेगा। यानी ग्राहक को इस अनुरोध को पुनः प्रयास करने से पहले कुछ बदलना होगा। उदाहरण के लिए, इस संसाधन में "संसाधन नहीं मिला" (HTTP 404) या "विकृत अनुरोध" (HTTP 400) त्रुटियां गिर जाएगी।

प्वाइंट 4: प्रमाणीकरण कैसे करें

जैसा कि बिंदु 1 में इंगित किया गया है, उपयोगकर्ता को प्रमाणित करने के बजाय, आप सत्र बनाने के बारे में सोच सकते हैं। उपयुक्त HTTP स्टेटस कोड (200: एक्सेस अनुमोदित या 403: एक्सेस अस्वीकृत) के साथ आपको एक नया "सत्र आईडी" वापस कर दिया जाएगा।

फिर आप अपने रिस्टफुल सर्वर से पूछेंगे: "क्या आप मुझे इस सत्र आईडी के लिए संसाधन प्राप्त कर सकते हैं?"।

कोई प्रमाणीकृत मोड नहीं है - आरईएसटी स्टेटलेस है: आप एक सत्र बनाते हैं, आप सर्वर से इस सत्र आईडी का उपयोग पैरामीटर के रूप में आपको संसाधन देने के लिए कहते हैं, और लॉगआउट पर आप सत्र को छोड़ देते हैं या समाप्त कर देते हैं।





rest