क्या मुझे मशीन पठनीय प्रारूप में आरईएसटी सेवाओं का वर्णन करना चाहिए?

Question

अधिकांश आरईएसटी इंटरफेस जिन्हें मैं देखता हूं, यूआरएल, विधि, स्वीकृत इनपुट और परिणाम लौटाते हुए एक साधारण वेब पेज के साथ वर्णित है। उदाहरण के लिए Amazon S3 या Twitter API दस्तावेज़ीकरण।

लेकिन मुझे अमेज़ॅन या ट्विटर के लिए पर्याप्त रूप से पर्याप्त चीज़ों के साथ क्यों निपटना चाहिए ... तो, क्या एक मशीन पठनीय प्रारूप में एक आरईएसटी एपीआई का वर्णन करना उचित है? और यदि हां, तो कौन सा?

डब्ल्यूएसडीएल 2.0 दावे capable of describing REST है। WADL स्पष्ट रूप से आरईएसटी सेवाओं का वर्णन करने के लिए बनाया गया है। डब्लूएसडीएल 2.0 और डब्ल्यूएडीएल दोनों में एक छोटा सा एटीएम लगता है और यह विवरण दस्तावेजों को बनाने और बनाए रखने के प्रयास के लिए थोड़ा सा वापसी प्रतीत होता है। मेरा अनुमान मूल रूप से मेरी धारणा को मान्य या अस्वीकार करने के लिए है।

क्या आप अपनी सेवाओं का वर्णन करने के लिए डब्लूएसडीएल/डब्ल्यूएडीएल का उपयोग करते हैं? क्या आप दूसरों की सेवाओं का उपभोग करने के लिए डब्लूएसडीएल/डब्ल्यूएडीएल पर भरोसा करते हैं? क्या आपकी पसंद का टूल इस समय किसी एक का समर्थन करता है?

मुझे लगता है कि WADL साइट के समान है HTML पृष्ठों के लिए नक्शे:

Answer 1

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

मुझे लगता है कि कारण सरल है - एक साइट के चारों ओर घूमना और रणनीतिक रूप से रखा बटन दबाकर अक्सर जटिल मानचित्र ब्राउज़ करने से काफी अधिक फायदेमंद होता है।

REST API विधियों को औपचारिक विवरण की आवश्यकता नहीं होनी चाहिए। इसलिए यदि एपीआई को विचारपूर्वक बनाया गया है तो 'संसाधन' के पुनर्स्थापित संसाधन के रणनीतिक रूप से रखा यूरी लिंक का पालन करके सभी संसाधनों को खोजना बहुत आसान है।

Answer 2

मशीन-पठनीय आरईएसटी एपीआई परिभाषा का क्या फायदा है?

आरईएसटी का बिंदु एपीआई अपेक्षाकृत सरल और आसानी से समझने के लिए है। प्राकृतिक भाषा इसके लिए अच्छी तरह से काम करती है।

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

"मशीन पठनीय" एपीआई होने से डीआरवाई सिद्धांत का उल्लंघन करते हुए आसानी से एपीआई स्रोत कोड दोहराया जा सकता है।

आरईएसटी क्रियाओं और यूआरआई के क्या हैं, इसके अंग्रेजी विवरण लिखना अक्सर आसान होता है। जेएसओएन (या वाईएएमएल या जेएक्सबी) के माध्यम से स्रोत कोड के रूप में मार्शल किए गए प्रकार को भेजें। यह सही मशीन-पठनीय एपीआई है - संदेश ऑब्जेक्ट क्लास के लिए वास्तविक कार्य स्रोत।

Answer 3

यहां एक चिकन/अंडे फेनोनेन है। WADL उपकरण के बिना बेकार है जो इसे उत्पन्न या उपभोग करता है। उपकरण बेकार हैं जब तक कि साइटें WADL प्रकाशित नहीं करतीं। आदि

मेरे लिए, अमेज़ॅन मॉडल ठीक काम करता है। अपने दर्शकों के आधार पर आपको स्निप ओडी नमूना संवाद सहित नमूने तैयार करने के प्रयास पर अधिक वापसी मिलेगी (अनुरोध 1 के लिए अनुरोध 1 जैसा दिखता है, फिर प्रतिक्रिया 2 के लिए, फिर अनुरोध 2, प्रतिक्रिया 2, आदि), और vvarious में कोड भाषाएं जो आपके लिए महत्वपूर्ण हैं। यदि आप मशीन-पठनीय परिभाषा पर जाना चाहते हैं, तो आप एक्सएसडी का उपयोग कर सकते हैं यदि यह एक एक्सएमएल संदेश प्रारूप है। जाहिर है यह WADL नहीं है लेकिन आपके अंग्रेजी विवरण के साथ, यह डेवलपर्स के लिए थोड़ा अतिरिक्त उपयोगिता प्रदान कर सकता है।

Answer 4

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

Answer 5

डब्लूएसडीएल (और उसी तरह डब्ल्यूएडीएल) का सबसे लोकप्रिय उपयोग कोड जनरेशन है। यह निश्चित रूप से विकास को गति में मदद करता है, लेकिन कुछ भी पुराने पुराने दस्तावेज को प्रतिस्थापित नहीं कर सकता है। मनुष्यों के लिए और मशीनों के लिए नहीं।