क्या HTTP API को हमेशा एक बॉडी वापस करना चाहिए?

Question

क्या HTTP API प्रतिक्रियाओं के बारे में किसी प्रकार का मानक है?

इस प्रवचन सूत्र को पढ़ने के बाद मुझे आश्चर्य होने लगा। हम अपने काम पर अपने सार्वजनिक HTTP JSON एपीआई का विकास कर रहे हैं, और जब कुछ सख्ती की जरूरत नहीं है, तो हम कुछ भी नहीं लौटाते हैं (उदाहरण के लिए एक PUT to / resource / {id} केवल 200 रिटर्न देता है जब ठीक या संबंधित 4XX या 5XX कोड, लेकिन नहीं JSON बॉडी)

क्या हमें एक जेनेरिक लौटना चाहिए {"success":true}जैसे कि वे ऊपर दिए गए लिंक पर चर्चा करते हैं, या "शून्य" बॉडी को वापस करना ठीक है और अन्य प्रतिक्रिया कोड के साथ सब कुछ संभालना है?

Comments

{"सफलता": सच} बेमानी लगता है। इसके बजाय HTTP कोड का बेहतर उपयोग करने का प्रयास करें। w3.org/Protocols/rfc2616/rfc2616-sec9.html

— CodeART

HTTP 1.1 में HEAD का परिचय दिया गया है जिसमें शरीर का अभाव है, यह केवल GET की हेडर प्रतिक्रिया है।

— बोक्टुलस

Answer 1

PUT के बारे में, लेकिन POST पर भी लागू होता है। HTTP विनिर्देशन धारा 9 नियम या यहाँ तक कि सलाह (चाहिए) पर एक छोटे से खाली जब यह परिदृश्य है कि आप का वर्णन कर रहे हैं करने के लिए आता है। आपके प्रश्न के लिए प्रासंगिक लाइन सबसे अधिक निकटता से कवर की गई है:

यदि कोई नया संसाधन बनाया जाता है, तो मूल सर्वर 201 (बनाया गया) प्रतिक्रिया के माध्यम से उपयोगकर्ता एजेंट को सूचित करेगा। यदि किसी मौजूदा संसाधन को संशोधित किया जाता है, तो 200 (ओके) या 204 (कोई सामग्री नहीं) प्रतिक्रिया कोड SHOULD को अनुरोध के सफल समापन को इंगित करने के लिए भेजा जाना चाहिए।

मुझे नहीं लगता कि मैं इस पर कोई नींद खो सकता हूं, लेकिन मैं पूछता हूं कि प्रतिक्रिया में JSON का हिस्सा जोड़कर आपको क्या हासिल होगा? आपने अभी-अभी बल्क किया है (ठीक है, थोक किया जा सकता है!) प्रतिक्रिया कम सटीक रूप से दोहरा रही है कि स्थिति कोड आपको पहले ही बता देना चाहिए। यदि आपका PUT एक नए ऑब्जेक्ट रिटर्न 201 में परिणत हुआ (जैसा कि PUT का इरादा है), यदि उसने ऑब्जेक्ट रिटर्न 204 अपडेट किया।

संयोग से, एपीआई एक तरफ, 200 के बजाय, यदि आप कुछ भी वापस नहीं करते हैं तो 204 का उपयोग करें।

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

Comments

POST के साथ, आप संभवतः एक ऐसे संसाधन पहचानकर्ता के साथ प्रतिक्रिया करना चाहेंगे जिसका उपयोग इसे आगे हेरफेर करने के लिए किया जा सकता है। POST /resource-> { "self" : "/resource/5" }।

— अरे

@ मैं उसके लिए locationhttp हैडर का उपयोग करूँगा ।

— कोडइन्चोस

@CodesInChaos हाँ, यह पूरी तरह से वैध है, हालांकि मैंने वास्तव में इसे व्यवहार में इस तरह से कभी नहीं देखा है और शायद वह उपभोक्ता के रूप में पसंद नहीं करेगा।

— हे

उपयोग मामला यह है कि ग्राहक वैध JSON की अपेक्षा कर रहा है, भले ही प्रतिक्रिया "खाली" हो या कोई सामग्री न हो। एक अच्छा उदाहरण JQuery है, जैसा कि नीचे Abhi द्वारा उल्लेख किया गया है।

— बी सेवन

Answer 2

आधार HTTP मानक यह अनिवार्य नहीं करता है कि प्रतिक्रिया के साथ कोई दस्तावेज़ लौटाया जाए। अर्थव्यवस्था की खातिर, जब एक HTTP स्थिति सभी को बताती है कि शरीर बेकार है। हालाँकि, HTTP के शीर्ष पर निर्मित मानक हैं जो नए नियम जोड़ते हैं।

एक खुला JSON API मानक है जो निर्दिष्ट करता है:

• एक JSON ऑब्जेक्ट प्रत्येक JSON API प्रतिसाद दस्तावेज़ के मूल में होना चाहिए । (इटालिक्स पाठ को स्पष्ट करने के लिए मैंने जो जोड़ा है उसका प्रतिनिधित्व करता है)

दुर्भाग्य से, मानक यह निर्दिष्ट नहीं करता है कि एक खाली दस्तावेज़ का प्रतिनिधित्व कैसे किया जाए, और यह एक कार्य प्रगति पर है। सबसे अच्छा मैं इसे एक दिशानिर्देश के रूप में उपयोग करूँगा।

कुछ एप्लिकेशन (जैसे ElasticSearch ) एक पूर्ण JSON एपि प्रदान करते हैं, और हमेशा कुछ मेटाडेटा रखते हैं ताकि आप बेहतर तरीके से जान सकें कि सर्वर आपके डेटा को कैसे प्रबंधित कर रहा है। मानक प्रतिक्रिया ऑब्जेक्ट आपको सूचकांक के स्वास्थ्य के बारे में बताता है, अगर अनुरोध में त्रुटि हुई, कितने नोड प्रभावित हुए, आदि। ElasticSearch माइम-प्रकार के लिए "एप्लिकेशन / जोंस" का उपयोग करता है, इसलिए यह संभावना नहीं है कि वे दिशानिर्देशों को लागू कर रहे हैं। jsonapi.org मानक।

JQuery और इसी तरह के जावास्क्रिप्ट फ्रेमवर्क यह मानते हैं कि हमेशा एक दस्तावेज होगा। सवाल यह है कि आप अपने API उपभोक्ताओं पर कितनी त्रुटि जाँच करना चाहते हैं? यदि आप सभी प्रतिक्रियाओं के लिए एक मानक प्रारूप के साथ आते हैं, जो केवल अनुरोध के प्रकार के आधार पर बढ़ाया जाता है, तो आप रिटर्न दस्तावेज़ की आवश्यकता को पूरा करते हैं, और अपने एपीआई उपभोक्ताओं द्वारा आसान डिबगिंग की सुविधा प्रदान कर सकते हैं।

Comments

यह। जब मैं एक JSON API सर्वर के लिए एक अनुरोध भेजता हूं, तो सबसे पहले मैं जांचता हूं कि प्रतिक्रिया वैध JSON है या नहीं। यदि यह मान्य नहीं है, तो मुझे लगता है कि यदि मुझे 200 प्रतिसाद मिला तो भी मैं अनुरोध को विफल कर दूंगा। रिक्त प्रतिक्रिया / स्ट्रिंग मान्य JSON नहीं है।

— अभि बेकर्ट

Answer 3

कोई उदाहरण के लिए, 204 प्रतिक्रिया के लिए हम संदेश के मुख्य भाग में शामिल नहीं होना चाहिए। {सफलता | स्थिति | असफल: सत्य} निरर्थक है।

व्यवहार में (या मुझे jquery के बाद के संस्करण में कहना चाहिए), आवेदन / json सामग्री प्रकार के लिए खाली प्रतिक्रिया त्रुटि उठाती है। मैं इस तर्क को समझता हूं कि क्योंकि यह एप्लिकेशन / जोंस है, इसमें एक वैध जसन बॉडी होना चाहिए। इसलिए, आवेदन / json सामग्री प्रकार के लिए खाली प्रतिक्रिया 'null' या '{}' होगी जो मान्य json हैं।

वहाँ एक और तरीका है जो jquery के लिए काम करना चाहिए, कि खाली प्रतिक्रियाओं के लिए आवेदन / json नहीं लौट रहा है। बस पाठ / सादा या कुछ का उपयोग करें और सुनिश्चित करें कि ग्राहक उस प्रकार को संभाल सकता है।

नोट मैं केवल 204 को वापस लौटने के संदेश के शरीर के लिए स्पष्ट रूप से याद कर सकता हूं। हमने पाया है कि हम हमेशा 204 का उपयोग नहीं कर सकते। समस्या 204 प्रतिक्रियाओं के लिए MSIE ड्रॉप प्रतिक्रिया हैडर है, इसलिए कोई सामग्री और हेडर नहीं है, जो खराब है। चूंकि कई MSIE का उपयोग कर रहे हैं, हमें इसे 200 स्थिति में बदलना पड़ा।

Answer 4

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

Answer 5

मैं प्रतिक्रिया में केवल सफलता की स्थिति नहीं लौटाऊंगा, http त्रुटि कोड केवल सफलता या त्रुटि का संकेत देता है। मैं केवल विस्तृत त्रुटि जानकारी जैसे एप्लिकेशन विशिष्ट त्रुटि कोड या त्रुटि संदेश जोड़ने के लिए प्रतिक्रिया का उपयोग करना शामिल करूंगा।

PUT, PATCH और POST अनुरोधों के लिए आप आमतौर पर अनुरोध लागू होने के बाद संसाधन की स्थिति को वापस कर देते हैं, खाली प्रतिक्रिया नहीं।

POST अनुरोधों के लिए, जो केवल एक संसाधन बनाने के बजाय एक क्रिया का प्रतिनिधित्व करते हैं (बहुत Restful नहीं है, लेकिन अभी भी व्यवहार में उपयोगी है), जिसमें वापस लौटने के लिए उपयोगी डेटा नहीं है, मैं एक खाली json ऑब्जेक्ट से मिलकर एक प्रतिक्रिया वापस करूँगा, अर्थात {}। इस तरह से क्लाइंट को एक वैध प्रतिक्रिया मिलती है और बाद में कुछ जानकारी जोड़ने से इसे तोड़ने की संभावना नहीं है।

DELETE अनुरोधों के लिए 204 और एक खाली बॉडी बहुत आम है, जो समझ में आता है क्योंकि संसाधन बाद में मौजूद नहीं है।

Answer 6

मेरा सुझाव है कि केवल उसी चीज़ को वापस करने की आवश्यकता है जो थोड़ी सी स्पष्ट है।

उदाहरण के लिए, आपके एपीआई का उपयोग कैसे किया जाए, इस पर निर्भर करते हुए, आप ऑब्जेक्ट की एक कॉपी शामिल कर सकते हैं, जैसा कि सहेजे जाने के बाद मौजूद है।

इसलिए {कुंजी: 123} का एक पोस्ट {कुंजी: 123, फू: 'बार'} वापस आ सकता है।

मूल विचार यह है कि वस्तु को वापस करने के लिए फिर से इसके लिए क्वेरी करना बेहतर है।

कहा कि, आपके API उपभोक्ताओं को उस वस्तु की आवश्यकता नहीं है जिसे वापस करने की कोई आवश्यकता नहीं है।

मैं आमतौर पर {सफलता: सच्चा} या कुछ ऐसे लौटाता हूं, जब POST PUT और PATCH पर किसी वस्तु की आवश्यकता नहीं होती है क्योंकि यह प्राप्त अंत के लिए आसान बनाता है। उस ने कहा, यह वस्तु के बचाया प्रतिनिधित्व को वापस करने के लिए 99% बेहतर है, यह दुर्लभ है कि उन्हें वैसे भी इसकी आवश्यकता नहीं होगी, और यह "सस्ता" है यह सब एक अनुरोध में दो में भेजने के लिए।

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

200 {सफलता: सच्चा} वापस करने से लोग दोनों तरह से कोड लिख सकते हैं:

if response.code == 200
  do stuff
end

तथा

if response.body.success
  do stuff
end

इसके अलावा यह आपके पक्ष में करने के लिए मुश्किल नहीं है।

अंत में, (पोसो उत्तर संरचना के लिए खेद है), एक सार्वजनिक JSON एपीआई प्रदान करके यह कैसे उपयोग किया जा रहा है पर बहुत नियंत्रण देता है। कुछ ग्राहक अलग-अलग निकायों (या वहां की कमी) या स्थिति कोड के लिए अलग-अलग प्रतिक्रिया कर सकते हैं।

Comments

+1 के लिए "केवल वही प्राप्त करें जो आवश्यक हो (और अधिक नहीं)"

— निकोलस रोसेंक्रांटज