🎳 🧝🏽 👲🏾 एपीआई से पहले स्वैगर पर रैमएल पर सिंगल कॉन्ट्रैक्ट ✋ 🌉 🌈

हाय% उपयोगकर्ता नाम%!

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

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

कटौती के तहत:

पहले एपीआई के सिद्धांतों का एक संक्षिप्त विवरण;
एकल अनुबंध - एक अवधारणा का परिचय, उपस्थिति के लिए आवश्यक शर्तें, OAS (स्वैगर) के आधार पर इसके कार्यान्वयन की संभावना पर विचार;
RAML + एनोटेशन + एकल अनुबंध के लिए आधार के रूप में ओवरले, उदाहरण;
RAML की समस्याएं, डेवलपर्स की वैचारिक असहमति;
उपरोक्त विचार (ऊपर प्रोटोटाइप चित्र) के आधार पर सास सेवा का विचार।

एपीआई से पहले स्वैगर पर रैमएल पर सिंगल कॉन्ट्रैक्ट

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

संचार के ऐसे एकल बिंदु के लिए एक औपचारिक और अस्पष्ट परिभाषा की आवश्यकता होती है, यह दस्तावेज़ एक एपीआई विनिर्देश है। आज एपीआई विनिर्देशों को विकसित करने और दस्तावेज करने के लिए, विभिन्न तकनीकों और भाषाओं का उपयोग किया जाता है, उदाहरण के लिए: OAS (स्वैगर), Apiary और RAML।

निम्नलिखित तीन बिंदु एपीआई पहले दृष्टिकोण की प्रकृति का निर्धारण करते हैं:

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

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

एकल अनुबंध। अनुबंध उपकरण और पुस्तकालय

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

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

प्रलेखन जनरेटर
मॉक-सर्वर एपीआई
तनाव परीक्षण सेवा
अनुरोध / प्रतिक्रिया सत्यापन पुस्तकालय
कोड जनरेटर
यूआई जनरेटर
और टी। डी।

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

एक अनुबंध विवरण उपकरण के रूप में स्वैगर (OAS)

मार्केट स्वैगर (OAS) और अपिरियर (ब्लूप्रिंट) पर मौजूद सबसे लोकप्रिय आपको विशेष भाषाओं का उपयोग करके HTTP API का वर्णन करने की अनुमति देता है: YAML या JSON पर आधारित ओपन एपीआई, मार्कडाउन पर आधारित ब्लूप्रिंट, जो विनिर्देशों को पढ़ने में आसान बनाता है। बड़े खुले स्रोत समुदाय द्वारा निर्मित कई उपकरण और पुस्तकालय भी हैं। स्वैगर वर्तमान में व्यापक रूप से वितरित किया गया है और, एक कह सकता है, पहले एपीआई का वास्तविक मानक बन गया है। कई बाहरी प्रणालियाँ स्वैगर विनिर्देशों के आयात का समर्थन करती हैं, जैसे कि सोपुई , रीडमे.आईओ , एपिगी , आदि। इसके अलावा, मौजूदा सास स्वैगर हब और एपरीर उपयोगकर्ताओं को प्रोजेक्ट बनाने, अपलोड करने या अपनी विशिष्टताओं को बनाने की अनुमति देता है, अंतर्निहित प्रलेखन जनरेटर और मॉक-सर्वर का उपयोग करता है, साथ ही बाहर से उन्हें एक्सेस करने के लिए लिंक प्रकाशित करता है।

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

पेशेवरों:

विवरण भाषा पढ़ने के लिए स्पष्ट और आसान;
बड़े खुले स्रोत वाले समुदाय;
आधिकारिक और ओपन-सोर्स संपादकों, जनरेटर, पुस्तकालयों दोनों का एक बहुत;
एक मुख्य विकास टीम की उपस्थिति लगातार प्रारूप के विकास और सुधार पर काम कर रही है;
विनिर्देशों के लिए शेयरवेयर हब;
विस्तृत आधिकारिक दस्तावेज;
कम प्रवेश दहलीज।

विपक्ष:

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

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

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

हमारी कंपनी में, किसी एक परियोजना के विकास के दौरान (रिएक्ट एसपीए + एपीआई सर्वर), निम्नलिखित मॉक-सर्वर कार्यक्षमता की आवश्यकता थी:

अंकुरण की नकल। सर्वर को सूची अनुरोधों के जवाब में करंट पेजेज, नेक्स्टपेज, पेजटोटल फील्ड्स के पूरी तरह से यादृच्छिक मूल्यों को वापस नहीं करना चाहिए, लेकिन क्लाइंट से प्राप्त पृष्ठ मूल्य के आधार पर इन मेटापोल के मूल्यों की पीढ़ी के साथ पृष्ठांकन तंत्र के वास्तविक व्यवहार का अनुकरण करने में सक्षम होना चाहिए;
आने वाले अनुरोध के विशिष्ट पैरामीटर के आधार पर विभिन्न डेटा सेट वाले प्रतिक्रिया निकाय उत्पन्न करना;
नकली वस्तुओं के बीच वास्तविक संबंध बनाने की क्षमता: बार इकाई के foo_id क्षेत्र को पहले से उत्पन्न फू इकाई का उल्लेख करना चाहिए। यह मॉक सर्वर में idempotency समर्थन जोड़कर प्राप्त किया जा सकता है;
विभिन्न प्राधिकरण विधियों के काम की नकल: OAuth2, JWT, आदि।

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

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

समस्या: डेवलपर को बेस स्पेसिफिकेशन के बदलते संस्करणों के बाद सभी कॉन्फ़िगरेशन की प्रासंगिकता बनाए रखने के लिए मजबूर किया जाएगा, अक्सर पूरी तरह से अलग-अलग स्थानों और प्रारूपों में।

समान सिद्धांत पर काम करने वाली सेवाओं के कुछ उदाहरण:

SoapUI REST & SOAP इंटरफेस के परीक्षण के लिए एक प्रणाली है। स्वैगर विनिर्देश से एक परियोजना का आयात करने का समर्थन करता है। बुनियादी स्वैगर विनिर्देश को बदलते समय, एपीआई कॉल की सूची पर आधारित परियोजना का विन्यास समानांतर में मौजूद रहता है और इसके लिए मैनुअल सिंक्रोनाइज़ेशन की आवश्यकता होती है;
अन्य SmartBear उत्पाद;
Apigee एक एपीआई जीवन चक्र प्रबंधन सेवा है। यह स्वैगर विनिर्देशों का उपयोग टेम्पलेट्स के रूप में करता है, जिसके आधार पर यह आंतरिक सेवाओं के अपने कॉन्फ़िगरेशन को आरंभ करने की अनुमति देता है। कोई स्वचालित सिंक्रनाइज़ेशन भी नहीं है;
Readme.io एक ऐसी सेवा है जो आपको स्वैगर विनिर्देश के आधार पर सुंदर दस्तावेज बनाने की अनुमति देती है, और सेवा विनिर्देश को प्रोजेक्ट कॉन्फ़िगरेशन को अपडेट करके बुनियादी विनिर्देश में परिवर्तन पर नज़र रखने और संघर्ष को हल करने के लिए एक तंत्र भी है। निश्चित रूप से, इस सेवा को विकसित करने के लिए अनावश्यक जटिलता की आवश्यकता थी।

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

RAML, एनोटेशन, ओवरले

एक उपकरण को खोजने की इच्छा, जो पहले उल्लेख किए गए OAS प्रतिबंध को छोड़कर, हमें सभी क्लाइंट टूल के लिए विनिर्देशन को एक एकल अनुबंध के रूप में विचार करने की अनुमति देता है, हमें RAML भाषा से परिचित हो गया है। RAML के बारे में पर्याप्त लिखा है, आप इसे पढ़ सकते हैं, उदाहरण के लिए, यहाँ https://www.infoq.com/articles/power-of-raml । रैमएल डेवलपर्स ने अपनी अवधारणा के स्तर पर प्रतिरूपकता के लिए भाषा समर्थन में बिछाने की कोशिश की है। एपीआई, रिडिफाइन और इनहेरिट रेडी-मेड डेटा मॉडल तैयार करते समय अब प्रत्येक कंपनी या व्यक्तिगत डेवलपर अपना स्वयं का बना सकते हैं या तैयार सार्वजनिक शब्दकोशों का उपयोग कर सकते हैं। संस्करण 1.0 से शुरू, RAML 5 विभिन्न प्रकार के बाहरी मॉड्यूल का समर्थन करता है: इसमें शामिल हैं, पुस्तकालय, विस्तार, विशेषता, ओवरले , जो उनमें से प्रत्येक को कार्य के आधार पर यथासंभव लचीले रूप से उपयोग करने की अनुमति देता है।

यह रैमएल की मुख्य विशेषता पर चर्चा करने का समय है, जो कि उन कारणों के लिए जो पूरी तरह से समझ में नहीं आते हैं, ओएएस और ब्लूप्रिंट - एनोटेशन में कोई एनालॉग नहीं है।

RAML में एनोटेशन अंतर्निहित भाषा संरचनाओं में कस्टम मेटाडेटा संलग्न करने की क्षमता है।

यह यह RAML फ़ंक्शन था जो इस लेख को लिखने का कारण बना।

एक उदाहरण:

#%RAML 1.0 title: Example API mediaType: application/json # Annotation types block may be placed into external file annotationTypes: validation-rules: description: | Describes strict validation rules for the model properties. Can be used by validation library allowedTargets: [ TypeDeclaration ] type: string[] info-tip: description: | Can be used by Documentation generator for showing tips allowedTargets: [ Method, DocumentationItem, TypeDeclaration ] type: string condition: description: | Named example can be returned if condition is evaluated to true. Can be used by Intelligent mock server allowedTargets: [ Example ] type: string types: Article: type: object properties: id: type: integer title: string paragraphs: Paragraph[] createdAt: type: string (validation-rules): ["regex:/\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d(?:\.\d+)?Z?/"] Paragraph: type: object properties: order: type: integer (validation-rules): ["min:0"] content: string (validation-rules): ["max-length:1024"] /articles/{articleId}: get: (info-tip): This endpoint is deprecated description: Returns Article object by ID responses: 200: body: application/json: type: Article

उपयोगकर्ता एनोटेशन संरचनाओं में स्वयं RAML में स्पष्ट विवरण होना चाहिए। इसके लिए, एक विशेष एनोटेशनटेप्स अनुभाग का उपयोग किया जाता है, जिसमें से परिभाषाएं भी बाहरी मॉड्यूल पर ले जा सकती हैं। इस प्रकार, RAML API की आधार परिभाषा से जुड़े एनोटेशन के रूप में किसी बाहरी उपकरण के विशेष मापदंडों को परिभाषित करना संभव हो जाता है। विभिन्न बाहरी उपकरणों के लिए एनोटेशन की एक बड़ी संख्या के साथ बुनियादी विनिर्देश को अव्यवस्थित करने से बचने के लिए, उन्हें अलग-अलग फाइलों में स्थानांतरित करने की संभावना के लिए समर्थन है - ओवरले (और एक्सटेंशन भी), गुंजाइश द्वारा वर्गीकरण के साथ। यहाँ रामलोक दस्तावेज में ओवरले के बारे में क्या कहा गया है ( https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#overlays ):

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

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

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

मूल संरचना का एक उदाहरण:

 #%RAML 1.0 title: Phrases API mediaType: application/json types: Phrase: type: object properties: content: string /phrases: get: queryParameters: whoSaid: string responses: 200: body: application/json: type: Phrase

ओवरले:

 #%RAML 1.0 Overlay usage: Applies annotations for Intelligent mock server extends: example_for_article_2_1.raml annotationTypes: condition: description: | Named example can be returned if condition is evaluated to true type: string allowedTargets: Example /phrases: get: responses: 200: body: application/json: examples: firstExample: (condition): $whoSaid is Hamlet content: "To be, or not to be?" secondExample: (condition): $whoSaid is Homer Simpson content: "D'oh!"

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

उपरोक्त अवधारणा को नीचे दिए गए चित्र में दर्शाया गया है:

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

मौजूदा ऑनलाइन RAML संपादक https://github.com/mulesoft/api-designer के लिए एक विशेष संपादक या ऐड-ऑन विकसित करने का एक संभावित और सबसे स्पष्ट समाधान होगा। संपादन क्षेत्र अपरिवर्तित रहता है, लेकिन टैब बनाना संभव हो जाता है: प्रत्येक नया टैब एक ओवरले को संपादित करने के लिए एक विंडो है। मुख्य विंडो में विनिर्देश की बुनियादी संरचना को संपादित करते समय, सभी बनाए गए टैब में संरचनाएं भी बदलती हैं, और जब टैब-ओवरले में मौजूद मौजूदा एनोटेशन के साथ नई संरचना की असंगति का पता लगाया जाता है, तो एक चेतावनी दिखाई देती है। ऐसे संपादक का अधिक विस्तृत विचार एक अलग विषय है और गंभीर विचार के योग्य है।

मौजूदा घटनाक्रम

मौजूदा समाधानों की तलाश में, जो मेटा-सूचना का वर्णन करने के साधन के रूप में एनोटेशन का उपयोग करने के विचार को महसूस करने के करीब हैं, निम्नलिखित समाधान पाए गए:

https://github.com/raml-org/raml-annotations रिपॉजिटरी जिसमें RAML डेवलपर समुदाय द्वारा अनुमोदित आधिकारिक एनोटेशन हैं। वर्तमान संस्करण में, केवल OAuth2 एनोटेशन उपलब्ध हैं। बाहरी उपकरणों द्वारा उनका उपयोग विकसित एपीआई विनिर्देश के लिए OAuth2 कार्यान्वयन के पहलुओं का वर्णन करने वाली मेटा-जानकारी प्राप्त करने के लिए किया जा सकता है;
https://github.com/petrochenko-pavel-a/raml-annotations उपयोगकर्ता एनोटेशन लाइब्रेरी @ पेट्रोचेंको-पावेल- एक तार्किक समूह के साथ आवेदन के क्षेत्र के साथ। परियोजना अधिक प्रयोगात्मक है, लेकिन एनोटेशन का उपयोग करने के विचार को पूरी तरह से दर्शाती है। सबसे दिलचस्प एनोटेशन समूह:
- extraValidation.raml - विनिर्देश मॉडल के सत्यापन के लिए अतिरिक्त नियमों का वर्णन करने के लिए एनोटेशन। उदाहरण के लिए, उन्हें सर्वर लाइब्रेरी द्वारा RAML विनिर्देश के अनुसार प्रश्नों को मान्य करने के लिए इस्तेमाल किया जा सकता है;
- mock.raml - RAML विनिर्देश के आधार पर नकली सर्वर के विवरण का वर्णन करने के लिए एनोटेशन;
- semanticContexts.raml - RAML विनिर्देशन के व्यक्तिगत घोषित संरचनात्मक ब्लॉकों के शब्दार्थ संदर्भ की ओर संकेत करने वाले एनोटेशन;
- स्ट्रक्चरल.रामल - एनोटेशन वर्णित डोमेन मॉडल की समग्र संरचना में एक अलग RAML इकाई की भूमिका को स्पष्ट करता है;
- uiCore.raml - RAML विनिर्देश के आधार पर UI पीढ़ी के टूल द्वारा उपयोग के लिए संभव एनोटेशन का एक उदाहरण;

रिपॉजिटरी में यूआईएल विनिर्देश की डेटा संरचनाओं का वर्णन करने में आदिम के रूप में उपयोग के लिए उपयुक्त उपयोगिता प्रकार के पुस्तकालय भी हैं।

RAML की समस्या

बुनियादी विचार की कार्यक्षमता, प्रगति और बड़े सॉफ्टवेयर निर्माताओं (सिस्को, स्पिकवेयर, वीएमवेयर, आदि) से ध्यान हटाने के बावजूद, RAML में आज गंभीर समस्याएं हैं जो इसके सफल भाग्य के संबंध में घातक हो सकती हैं:

छोटे और खंडित खुले स्रोत वाले समुदाय;
मुख्य RAML डेवलपर की एक समझ से बाहर की रणनीति है। कंपनी ऐसे उत्पादों का विकास करती है जो मौजूदा OAS- आधारित समाधान ( Anypoint Platform में शामिल) की एक प्रति है, इसके बजाय सेवाओं को बनाने के लिए जो स्वैगर पर RAML के लाभों पर जोर देती हैं;
पहले पैराग्राफ का परिणाम: खुले स्रोत पुस्तकालयों / उपकरणों की एक छोटी संख्या;
OAS की तुलना में उच्च प्रवेश सीमा (यह अजीब है, लेकिन बहुत से लोग ऐसा सोचते हैं);
यूएक्स / यूआई के साथ बड़ी संख्या में बग और समस्याएं होने के कारण, मुख्य सेवा जो पूरी तरह से अनुपयुक्त है और उपयोगकर्ताओं को खदेड़ने के लिए RAML - https://anypoint.mulesoft.com/ का प्रवेश बिंदु है।

वैचारिक असहमति। पहला निष्कर्ष

मूल अवधारणा के बारे में समुदाय के भीतर विरोधाभास हैं। किसी को लगता है कि RAML एक मॉडल परिभाषा भाषा है , और कोई सोचता है कि यह OAS या ब्लूप्रिंट की तरह एक एपीआई परिभाषा भाषा है (जो लोग खुद को RAML डेवलपर्स कहते हैं, वे अक्सर विभिन्न टिप्पणियों में इसका उल्लेख करते हैं)। मॉडल परिभाषा भाषा की अवधारणा, RAML विनिर्देशन के अंदर API संसाधन विवरण के संदर्भ में टाइट बाइंडिंग के बिना डोमेन के डोमेन मॉडल का वर्णन करने की अनुमति देती है, जिससे बाहरी उपकरणों के साथ विनिर्देश का उपयोग करने के विकल्पों के क्षितिज का विस्तार होता है (वास्तव में, इस एकल अनुबंध के अस्तित्व की नींव का निर्माण!)। यहाँ एक संसाधन की अवधारणा की परिभाषा वेबसाइट रीडहाट डॉक्स ( http://restful-api-design.readthedocs.io/en/latest/resources.html) पर देखी जा सकती है, वैसे, मैं सभी को एपीआई डिजाइन पर इस अद्भुत गाइड को पढ़ने की सलाह देता हूं:

हम उन सूचनाओं को कहते हैं जो उपलब्ध संसाधनों के प्रकार , उनके व्यवहार और उनके रिश्तों को एक एपीआई के संसाधन मॉडल का वर्णन करती हैं। संसाधन मॉडल को एप्लिकेशन डेटा मॉडल के Restful मानचित्रण के रूप में देखा जा सकता है।

RAML एप्लिकेशन डेटा मॉडल में, ये प्रकार प्रकार ब्लॉक में घोषित किए गए हैं , और एक API का संसाधन मॉडल वह है जो संसाधन RAML ब्लॉक में वर्णित है। इसलिए, आपके पास इस मैपिंग का वर्णन करने की क्षमता होनी चाहिए। लेकिन RAML का वर्तमान कार्यान्वयन इस तरह की मैपिंग को केवल 1 से 1 तक करने की अनुमति देता है, जो कि संसाधन API घोषणा के अंदर "जैसा है" का उपयोग करना है।

मुझे लगता है कि यह भाषा की मुख्य समस्या है, जिसके समाधान से रैम को एपीआई परिभाषा भाषा से परे जाने और पूर्ण-विकसित मॉडल परिभाषा भाषा बनने की अनुमति मिलेगी: एक अधिक सामान्य भाषा (ओएएस या ब्लूप्रिंट के बजाय) सिस्टम के एकल अनुबंधों का वर्णन करने के लिए उपयोग की जाती है, जो मूल रूप से औपचारिक कोर हैं उनके कई घटक।

उपरोक्त RAML को एक कमजोर खिलाड़ी बनाता है जो वर्तमान में स्वैगर के खिलाफ प्रतियोगिता जीतने में असमर्थ है। शायद इसीलिए, RAML के मुख्य डेवलपर ने कठोर उपाय किए https://blogs.mulesoft.com/dev/api-dev/open-api-raml-better-tately/

सिंगल कॉन्ट्रैक्ट RAML सास का विचार

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

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

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

प्लगइन निर्देशिका को खुले स्रोत समुदाय द्वारा विस्तार के लिए खुला होना चाहिए। सशुल्क प्लग-इन को लागू करना भी संभव है, जो नए लोगों के विकास के लिए एक प्रोत्साहन के रूप में काम कर सकता है।

संभावित प्लगइन्स: एपीआई के लचीले मानकीकरण के लिए बड़ी संख्या में एनोटेशन के समर्थन के साथ एपीआई प्रलेखन, "स्मार्ट" मॉक सर्वर (ऊपर उदाहरण से), अनुरोधों या कोड पीढ़ी को मान्य करने के लिए डाउनलोड करने योग्य लाइब्रेरी, मोबाइल अनुप्रयोगों के लिए निवर्तमान एपीआई अनुरोधों के लिए डिबगिंग उपकरण (कैशिंग प्रॉक्सी), लोड परीक्षण एनोटेशन के माध्यम से प्रवाह परीक्षण के सेटअप के साथ, बाहरी सेवाओं के साथ एकीकरण के लिए विभिन्न प्लगइन्स।

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

दूसरा निष्कर्ष

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

आधिकारिक साइट RAML
सुस्त चैनल
विनिर्देश

आपका ध्यान के लिए धन्यवाद।

एपीआई से पहले स्वैगर पर रैमएल पर सिंगल कॉन्ट्रैक्ट