REST API अनुशंसाएँ - जावा और स्प्रिंग में वेब सेवा डिज़ाइन उदाहरण

इस श्रृंखला के अंतिम लेख में, आप जावा और स्प्रिंग वेब सेवाओं से REST API सिफारिशों और विकास उदाहरणों के बारे में जानेंगे।

एक अच्छे REST API को विकसित करते समय, अच्छे माइक्रोसरोवर्स का होना जरूरी है।
आप अपना REST API कैसे विकसित करते हैं? सर्वोत्तम अभ्यास क्या हैं?

आप सीखेंगे:

• एक अच्छा REST API कैसे विकसित करें?
• REST API विकसित करते समय मुझे क्या सोचना चाहिए?
• रेस्टफुल वेब सेवाओं को विकसित करने के लिए सर्वोत्तम अभ्यास क्या हैं?

अन्य एपीआई

यह रीस्ट एपीआई के बारे में लेखों की एक श्रृंखला का अंतिम लेख है:

• रेस्ट एपीआई का परिचय - रेस्टफुल वेब सर्विसेज
• REST और SOAP के बीच अंतर
• REST API डेवलपमेंट - कॉन्ट्रैक्ट फर्स्ट (अनुबंध पहले) क्या है?
• REST API डेवलपमेंट - कोड फर्स्ट (कोड फर्स्ट) क्या है?
• REST API - HATEOAS क्या है?
• REST API अनुशंसाएँ - जावा और स्प्रिंग में वेब सेवा डिज़ाइन उदाहरण

उपभोक्ता पहले दृष्टिकोण का उपयोग करें

आपकी सेवा का उपयोग कौन करेगा? उपभोक्ता सेवाएं

क्या आप उपभोक्ता के दृष्टिकोण से सेवा को देखते हैं?

• यदि आप एक एपीआई विकसित कर रहे हैं, तो क्या आपका उपभोक्ता आपके एपीआई को समझ सकता है?
• यदि आप अपने संसाधनों को प्रकाशित करते हैं, तो क्या उपभोक्ता उन्हें ढूंढ और प्राप्त कर सकता है?
• क्या उपभोक्ता आपके यूआरआई को समझ सकता है?
• आप किस प्रकार की सेवा प्रदान करते हैं?
• क्या यह एक मोबाइल एप्लिकेशन या वेब एप्लिकेशन है?
• आप उपभोक्ताओं से क्या उम्मीद करते हैं और क्या भविष्य में इस प्रकार के उपभोक्ता बदल सकते हैं?
• यदि आप HATEOAS जैसी कोई चीज़ लागू कर रहे हैं, तो सोचें कि इसे लागू करने से पहले आपके ग्राहक इसका उपयोग कैसे करेंगे।

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

जब भी आपके पास चर्चा या सेवा की समीक्षा हो, तो ग्राहकों की आवश्यकताओं को पहले स्थान पर रखें।

अनुबंध पहले दृष्टिकोण का उपयोग करें

एक अनुबंध क्या है?

वेब सेवा के निर्माता को सेवा प्रदाता माना जाता है । वेब सेवा का उपयोग करने वाला एप्लिकेशन सेवा का उपभोक्ता है । एक अनुबंध एक प्रदाता और एक उपभोक्ता के बीच एक सेवा के बारे में एक समझौता है।



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

• वेब सेवा कैसे कॉल करें?
• किस प्रकार के परिवहन का उपयोग किया जाता है?
• अनुरोध और प्रतिक्रिया संरचनाएं क्या हैं?

इसे सेवा परिभाषा भी कहा जाता है।

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

WSDL के साथ पहला अनुबंध

उदाहरण के लिए, जब आप SOAP वेब सेवाओं को परिभाषित करते हैं, तो आप अनुबंध को परिभाषित करने के लिए WSDL का उपयोग करते हैं।



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

अनुबंध पहले स्वैगर / ओपन एपीआई के साथ

जब आप रैस्टफुल वेब सेवाओं का उपयोग करते हैं, तो स्वैगर आपकी वेब सेवाओं के दस्तावेज के लिए एक लोकप्रिय उपकरण है।



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



यह प्रतिक्रिया कोड के बारे में विस्तृत जानकारी भी देता है जो इसका समर्थन करता है। आप यह भी देख सकते हैं कि यह विशेष संसाधन, / jpa / उपयोगकर्ता :



GET ऑपरेशन का समर्थन करता है। वास्तव में, यह POST ऑपरेशन का भी समर्थन करता है:



प्रतिक्रिया योजना, यदि यह संसाधन उपलब्ध है, तो यह होगा:



उपयोगकर्ता ऑब्जेक्ट की परिभाषा स्वैगर समझौते में मौजूद है:



इसमें विशेषताएँ शामिल हैं: जन्मतिथि , आईडी , नाम और पदों की एक सरणी संदेश। कुछ क्षेत्रों में उनके अंदर एक विवरण क्षेत्र भी शामिल है।

अनुबंध पहले दृष्टिकोण में, सेवा को लागू करने से पहले, आप मैन्युअल रूप से या एप्लिकेशन का उपयोग करके स्वैगर द्वारा बनाई गई परिभाषा बनाते हैं।

अनुबंध के लाभ पहले दृष्टिकोण

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

यदि प्रारंभिक चरण में आप कार्यान्वयन के लिए बहुत महत्व देते हैं, तो तकनीकी विवरण आपकी सेवा की परिभाषा को भेदते हैं।

आपको यह सुनिश्चित करने की आवश्यकता है कि आपकी सेवा की परिभाषा आपके द्वारा उपयोग किए जा रहे प्लेटफॉर्म पर निर्भर न हो, यह जावा, .NET या कोई अन्य हो।

रीस्ट एपीआई के लिए संगठन मानकों को परिभाषित करें

आपके संगठनात्मक मानकों के लिए एक महत्वपूर्ण दिशानिर्देश YARAS है।



YARAS अभी तक एक और विश्वसनीय एपीआई मानक के लिए खड़ा है। YARAS मानकों, दिशानिर्देशों, और सम्मेलनों को प्रदान करता है जिनका पालन Restful वेब सेवाओं को विकसित करते समय किया जाना चाहिए। वह निम्नलिखित बातों के लिए सिफारिशें देता है:

• आपको अपनी सेवाओं का नाम क्या देना चाहिए
• आपको अपने अनुरोध और प्रतिक्रिया की संरचना कैसे करनी चाहिए
• आपको फ़िल्टरिंग, सॉर्टिंग, पेजिनेशन और अन्य कार्यों को कैसे लागू करना चाहिए
• आपको किस तरह से वर्जनिंग करना चाहिए
• आपको API दस्तावेज़ीकरण की आवश्यकता कैसे है

सेवा विकास के लिए एकीकृत दृष्टिकोण

Restful वेब सेवाओं को डिज़ाइन करने से पहले आपको कई जटिल समस्याओं को हल करना होगा। उपरोक्त सभी, आपको पता लगाने की आवश्यकता है।

आपके संगठन का नेतृत्व ऐसी टीमों को नहीं चाहेगा जो विभिन्न संसाधनों के साथ इन चीजों के लिए अलग-अलग दृष्टिकोण रखती हैं।

उदाहरण के लिए, टीम-ए के लिए क्वेरी पैरामीटर के आधार पर वर्जनिंग को व्यवस्थित करना और URI के आधार पर वर्जनिंग का उपयोग करने के लिए टीम-बी का उपयोग करना अवांछनीय है।

इसलिए, यह महत्वपूर्ण है कि आपने Restful वेब सेवाओं के लिए अपने दृष्टिकोण के लिए संगठनात्मक मानकों को स्पष्ट रूप से परिभाषित किया है।

YARAS अनुकूलन UNDER संगठनात्मक आवश्यकताओं

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

• कॉन्फ़िगर करें कि अनुरोध और प्रतिक्रिया निकायों को कैसा दिखना चाहिए।
• एक विशिष्ट संस्करण नियंत्रण प्रणाली चुनें

चूंकि YARAS में काफी व्यापक कवरेज है, इसलिए आप सुनिश्चित हो सकते हैं कि आपने एक भी महत्वपूर्ण निर्णय नहीं लिया है।

एक मानक उद्यम ढांचा चुनना REST API फ्रेमवर्क

जावा दुनिया में रेस्टफुल वेब सेवाओं को बनाने के लिए उपयोग किए जाने वाले विशिष्ट ढांचे स्प्रिंग एमवीसी, स्प्रिंग रेस्ट और जेएक्स-आरएस हैं।

यदि आप एक संगठन-विशिष्ट फ्रेमवर्क / आर्किटाइप / संदर्भ एप्लिकेशन बनाते हैं जो पसंदीदा REST API प्लेटफॉर्म के शीर्ष पर सामान्य संगठन मानकों का पालन करता है, तो यह टीमों को आसानी से सामान्य मानकों का पालन करने की अनुमति देगा।

विशिष्ट विशेषताओं में शामिल हैं:

• अनुरोध और प्रतिक्रिया संरचनाएं
• हैंडलिंग में त्रुटि
• छानने
• खोज
• संस्करण
• गलत उत्तर समर्थन
• HATEOAS

मानक रूपरेखा पूरे संगठन में सेवाओं को डिजाइन और कार्यान्वित करने के लिए एक एकीकृत दृष्टिकोण प्रदान करती है।

विकेंद्रीकृत रीस्ट एपीआई प्रबंधन

REST API बनाने वाली टीमों के विशेषज्ञों का एक समूह बनाएँ और एक प्रबंधन टीम बनाएँ। टीम इसके लिए जिम्मेदार है

• अन्य एपीआई मानकों में सुधार
• बिल्डिंग / डिजाइनिंग आपका REST API फ्रेमवर्क

HTTP का व्यापक उपयोग

जब भी आप Restful वेब सेवाओं के बारे में सोचते हैं, तो HTTP के बारे में सोचें।

HTTP में सभी सुविधाएँ हैं जो आपको बेहतरीन वेब सेवाएँ बनाने में मदद करती हैं।

सही HTTP अनुरोध विधियों का उपयोग करें

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

HTTP विधियों का उपयोग करना:

• पाने के लिए
• पोस्ट बनाने के लिए
• अद्यतन करने के लिए PUT
• डिलीट करने के लिए DELETE करें
• आंशिक अद्यतन के लिए पाट

उचित HTTP प्रतिक्रिया स्थिति का उपयोग करें

ऑपरेशन करते समय, सुनिश्चित करें कि आप सही प्रतिक्रिया स्थिति लौटाते हैं।

उदाहरण के लिए, जब कोई विशिष्ट संसाधन नहीं मिलता है, तो सर्वर अपवाद को न फेंकें। इसके बजाय, एक प्रतिक्रिया संदेश में उपयुक्त प्रतिक्रिया कोड भेजें, जैसे कि 404 ।

यदि वास्तव में सर्वर अपवाद है, तो कोड 500 वापस भेजें।

यदि सत्यापन विफल हो जाता है, तो अमान्य अनुरोध के लिए कोड भेजें।

प्रदर्शन पर ध्यान दें

प्रत्येक संसाधन में कई प्रतिनिधित्व हो सकते हैं - XML ​​या JSON प्रारूप में। सेवा उपभोक्ता अपनी पसंद की प्रस्तुति चुन सकते हैं।

जब हम GET अनुरोध भेजते हैं तो यह सेवा 3 उपयोगकर्ताओं को वापस कर देती है। इस स्थिति में, हमें / उपयोगकर्ता संसाधन का JSON प्रतिनिधित्व मिलता है।



जब उपभोक्ता एक पसंदीदा दृश्य नहीं दिखाता है, तो हम JSON का उपयोग करते हैं।



उपभोक्ता दृश्य को इंगित करने के लिए एक स्वीकार्य हेडर भेज सकता है।



प्रतिक्रिया निकाय में अब XML सामग्री है:

बहुवचन का उपयोग करें

संसाधनों का नाम रखने पर हमेशा बहुवचन का उपयोग करें।

आइए एक साधारण उदाहरण देखें। मान लीजिए हमारे पास एक सेवा है जो एक उपयोगकर्ता संसाधन को होस्ट करती है। निम्नलिखित का वर्णन है कि उन्हें कैसे एक्सेस करना है:

• उपयोगकर्ता बनाएं: POST / उपयोगकर्ता
• उपयोगकर्ता हटाएं: DELETE / उपयोगकर्ता / 1
• सभी उपयोगकर्ता प्राप्त करें : GET / उपयोगकर्ता
• एक उपयोगकर्ता प्राप्त करें: GET / उपयोगकर्ता / 1

उपयोगकर्ता उपयोगकर्ता पर कई उपयोगकर्ताओं की प्राथमिकता URI को अधिक पठनीय बनाती है।

• उदाहरण के लिए, यदि हम पाने के लिए / उपयोगकर्ताओं के बजाय / उपयोगकर्ता का उपयोग करते हैं, तो GET / उपयोगकर्ता पाठक को सही संदेश नहीं देता है।

अच्छा प्रलेखन बनाएँ

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

SOAP वेब सेवाएँ WSDL कार्यक्षमता का उपयोग कर सकती हैं, जबकि RESTful वेब सेवाओं में Swagger विकल्प (अब Open API प्रलेखन मानक) हैं।

एक प्रारूप चुनना अच्छा प्रलेखन बनाने का केवल एक हिस्सा है। क्या महत्वपूर्ण है उपभोक्ता को मदद करने के लिए सूचना की सही मात्रा का प्रावधान है।

प्रलेखन पूरा होना चाहिए और निम्नलिखित बिंदुओं को शामिल करना चाहिए:

• अनुरोध और प्रतिक्रिया संरचना क्या है?
• एक उपभोक्ता को खुद को कैसे प्रमाणित करना चाहिए?
• उपयोग की सीमाएँ क्या हैं?
• सभी प्रकार के प्रतिक्रिया संदेश और संबंधित स्थिति कोड इंगित करें जो सेवा से अपेक्षित हो सकते हैं।

एक सामान्य REST API प्रलेखन पोर्टल बनाएँ

पूरे संगठन के लिए एक सामान्य REST API प्रलेखन पोर्टल होना सहायक होगा। ऐसे ही एक पोर्टल पर नज़र डालें:



ऐसा पोर्टल संगठन में उपलब्ध सभी संसाधनों को एक साथ लाता है। उपयोगकर्ता इंटरफ़ेस जैसे कि स्वैगर UI होने के अपने अतिरिक्त लाभ होंगे। स्वैगर UI का उपयोग करके, आप दस्तावेज़ को अधिक विस्तार से देख सकते हैं:



इसका उपयोग गैर-तकनीकी उपयोगकर्ताओं द्वारा भी किया जा सकता है। यहाँ दी गई जानकारी में शामिल हैं:

• अपेक्षित प्रतिक्रिया प्रारूप
• सामग्री प्रकार
• समर्थित उत्तर कोड

लाइव अनुरोध / प्रतिक्रिया की शैली में प्रलेखन प्रारूप भी रुचि का हो सकता है।

संस्करण का समर्थन

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

हालांकि, कुछ परिदृश्यों में, संस्करण नियंत्रण अपरिहार्य है।

आइए एक उदाहरण सेवा को देखकर शुरू करें। मान लें कि हमने शुरू में एक ऐसी सेवा को परिभाषित किया है, जिसमें निम्नानुसार व्यक्ति 1 वर्ग है:

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

इस विसंगति को ठीक करने के लिए स्रोत वर्ग के दूसरे संस्करण को अपडेट किया गया है:

हम तुरंत व्यक्ति सेवा का उपयोग करने के लिए पूरी सेवा को हस्तांतरित नहीं कर सकते हैं! ऐसे अन्य उपभोक्ता हो सकते हैं जिन्हें पर्सन 1 फॉर्मेट में प्रतिक्रियाओं का इंतजार है।

यह वह जगह है जहां संस्करण नियंत्रण की आवश्यकता है।

आइए अब इन दो संसाधनों के संस्करण नियंत्रण के लिए हमारे पास मौजूद विकल्पों को देखें।

विभिन्न यूआरआई का उपयोग करना

हमारे पास एक विकल्प है - इन विभिन्न संसाधनों के लिए अलग-अलग यूआरआई का उपयोग करना। नीचे दिए गए परीक्षा कोड में, हम URIs v1 / व्यक्ति और v2 / व्यक्ति का उपयोग उन्हें अलग करने के लिए करते हैं:

यदि आप संसाधन v1 / व्यक्ति के लिए GET अनुरोध निष्पादित करते हैं:



आपको v1 से संबंधित जानकारी प्राप्त होगी। किसी अन्य संसाधन के लिए:

क्वेरी पैरामीटर का उपयोग करना

दूसरा संस्करण नियंत्रण विधि क्वेरी पैरामीटर का उपयोग करता है:

URI / व्यक्ति / परम में , अगर हम पैरामीटर को संस्करण = 1 के साथ भेजते हैं, तो हम प्रकार के एक संसाधन को लौटाते हैं PersonV1 :



समान URI के लिए, संस्करण = 2 के साथ पैरामीटर प्रकार का एक व्यक्ति देता है PersonV2 :



इस विधि को क्वेरी पैरामीटर का उपयोग करके संस्करण कहा जाता है।

हेडर (हैडर) का उपयोग करना

दूसरा तरीका यह है कि आप किसी शीर्षक को निर्दिष्ट करके संस्करण नियंत्रण कर सकते हैं। यहां हम X-API-VERSION नामक हेडर का उपयोग करते हैं और यूआरआई को / व्यक्ति / हेडर के रूप में चिह्नित करते हैं। जब हेडर मान 1 होता है , तो टाइप पर्सन 1 का एक संसाधन लौटाया जाता है :



जब इसका मान 2 होता है , तो व्यक्ति प्रकार का एक संसाधन पुनर्प्राप्त किया जाता है:



हम अपने लिए संस्करण नियंत्रण करने के लिए अनुरोध शीर्ष लेख में विशेषता का उपयोग करते हैं।

स्वीकार हैडर का उपयोग करना

संस्करण बनाने की अंतिम विधि स्वीकार हैडर का उपयोग करती है। यदि उपभोक्ता GET अनुरोध के स्वीकारकर्ता के पहले संस्करण की जानकारी शामिल करता है, तो निम्न संसाधन वापस आ जाता है:



अन्यथा, टाइप व्यक्ति -2 का एक संसाधन लौटाया जाता है :



इस संस्करण नियंत्रण विधि को स्वीकार हैडर संस्करण या मीडिया प्रकार संस्करण कहा जाता है, क्योंकि MIME प्रकार आमतौर पर स्वीकृत शीर्षक की सामग्री होते हैं।

संस्करण नियंत्रण विधियों की तुलना

अब तक हमने चार प्रकार के तरीकों को देखा है:

• विभिन्न यूआरआई का उपयोग करना
• क्वेरी पैरामीटर का उपयोग करना
• हेडर का उपयोग
• स्वीकार हैडर / मीडिया प्रकार का उपयोग करना

कौन सा सबसे अच्छा है? सच तो यह है कि इस सवाल का एक भी जवाब नहीं है। इस तथ्य का तथ्य यह है कि विभिन्न इंटरनेट दिग्गज विभिन्न प्रकार के संस्करणों का संरक्षण करते हैं।

• विभिन्न यूआरआई का उपयोग करना - ट्विटर
• क्वेरी पैरामीटर का उपयोग करना - अमेज़ॅन
• एक हैडर का उपयोग करना - Microsoft
• स्वीकार हैडर / मीडिया प्रकार का उपयोग करना - GitHub

आपको अपनी विशिष्ट आवश्यकताओं के अनुसार इन चार विकल्पों का मूल्यांकन करने की आवश्यकता है। विचार करने के लिए कई महत्वपूर्ण कारक हैं:

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

समझें कि कोई एकल आदर्श समाधान नहीं है!

त्रुटि से निपटने के बारे में सोचें

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

जब कोई उपभोक्ता एक गैर-मौजूद संसाधन का अनुरोध करता है

यदि हम किसी मौजूदा उपयोगकर्ता को खोजने के लिए GET अनुरोध भेजते हैं, तो हमें निम्न प्रतिक्रिया मिलती है:



यदि आप किसी न किसी उपयोगकर्ता की तलाश कर रहे हैं:



आपको जो मिल रहा है वह 404 Not Found स्टेटस है। यह एक अच्छी त्रुटि हैंडलिंग है क्योंकि यह सही ढंग से निर्धारित करता है कि संसाधन नहीं मिला था और सर्वर त्रुटि वापस नहीं करता है।

चलिए अब एक बिना किसी URI के GET अनुरोध भेजें:



जैसा कि आप देख सकते हैं, आपको 404 Not Found response स्टेटस मिलते हैं। अमान्य URL एक ऐसे संसाधन को इंगित करता है जो मौजूद नहीं है।

महत्वपूर्ण प्रतिक्रिया की स्थिति

• 200 - सफलता
• 404 - संसाधन नहीं मिला
• 400 - अमान्य अनुरोध (उदाहरण के लिए, सत्यापन त्रुटि)
• 201 - बनाया गया
• 401 - अनधिकृत (यदि प्रमाणीकरण विफल रहता है)
• 500 - सर्वर त्रुटि

रिस्पांस बॉडी में त्रुटि विवरण

यह आपकी सेवा को विकसित करते समय एक मानक अपवाद संरचना होने पर मदद करता है।



विशिष्ट त्रुटियों के लिए, विशिष्ट प्रतिक्रिया संरचनाएं उपभोक्ता को लौटाई जा सकती हैं, और यह पूरे संगठन में मानक हो सकता है। सुनिश्चित करें कि त्रुटि प्रतिक्रिया उपभोक्ताओं के लिए भी पठनीय है, भ्रम के बिना।

स्वैगर या ओपन एपीआई डॉक्यूमेंटेशन का उपयोग करना

स्वैगर रेस्टफुल वेब सेवाओं के लिए सबसे लोकप्रिय प्रलेखन प्रारूपों में से एक प्रदान करता है। आज यह विभिन्न संगठनों द्वारा समर्थित है और बड़ी संख्या में सेवाओं में उपयोग किया जाता है। यहाँ हम स्वैगर के दो मुख्य पहलुओं पर नज़र डालते हैं:

• स्वैगर प्रलेखन प्रारूप
• स्वैगर यूआई, जो आपको नेत्रहीन सुविधाजनक तरीके से स्वैगर प्रलेखन को देखने की अनुमति देता है

स्वैगर डॉक्यूमेंटेशन

निम्नलिखित स्वैगर JSON पर एक नज़र डालें:



शीर्ष स्तर पर, यह डब्ल्यूएसडीएल की परिभाषा के समान दिखता है। इसकी कई महत्वपूर्ण विशेषताएं हैं:

• होस्ट : जहां सेवा स्थित है
• आधारपथ : वह मार्ग जहाँ सेवा स्थित है
• खपत : क्या अनुरोध स्वीकार किए जाते हैं

• उत्पादन : किस प्रकार की प्रतिक्रियाएं उत्पन्न होती हैं

• पथ : विभिन्न संसाधन उपलब्ध हैं इस मामले में, आपके पास सूची में कई प्रकार के संसाधन हैं:

जब आप स्वैगर डॉक्यूमेंटेशन को देखते हैं, तो आप प्रत्येक संसाधन से संबंधित उपलब्ध संसाधन, समर्थित संचालन और संचालन की शीघ्रता से पहचान कर सकते हैं:



/ उपयोगकर्ता संसाधन GET और POST परिचालनों का समर्थन करता है। GET के लिए, आप समर्थित अनुरोध और प्रतिक्रिया प्रकार देख सकते हैं। आप विभिन्न प्रकार के उत्तर भी देखते हैं:



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



स्वैगर उस तकनीक से पूरी तरह से स्वतंत्र है जिसका उपयोग आप एक रैस्टफुल वेब सेवा को लागू करने के लिए करते हैं। ओह, सब कुछ JSON आधारित है।

पेश है स्वैगर यूआई

Swagger UI — , Swagger - RESTful. :



, - . :



, :



, URL :



GET , :



, . birthDate , id , links , name posts . :

Swagger ( Open API)

Swagger — , . , , : :



Swagger contract-first, code-first.

.

RESTful -.

Be the BEST at Your REST API!

Developing REST APIs