आपके प्रोजेक्ट के लिए एक महत्वपूर्ण एपीआई के महत्वपूर्ण पहलू

यह लेख मेरे सिर में लंबे समय से चल रहा है, लेकिन एक पूरी तरह से अलग प्रारूप में।

WEB सेवाओं के विषय पर पिछले कुछ अजीब लेख पढ़ने के लिए (उदाहरण के लिए: http://habrahabr.ru/blogs/development/108973/ ) और उनमें REST तकनीक का उपयोग, मैंने तय किया कि यह आलस्य को दूर करने, समय आवंटित करने और लिखने का समय था मेरे लेख में "सुधारित"।

तो, संक्षेप में, आप लेख में क्या पाएंगे और यह किसके लिए उपयोगी होगा:



- शुरुआती लोगों के लिए जो परियोजना के लिए एक वेब सेवा लिखने के लिए इच्छुक हैं या योजना बना रहे हैं

- पेशेवरों को अपने लिए कुछ नया मिलने की संभावना नहीं है

- सामान्य रीति विचारधारा

- वेब सेवाओं में सीआरयूडी का अनुप्रयोग

- रूटर के निर्माण में KISS सिद्धांतों

- सर्वोत्तम अभ्यास

- थोड़ा पीआर;)

- संदर्भ, साहित्य



आपके लिए निर्णय लेना कहां से शुरू होता है, मैं सलाह देता हूं कि आप पहले लेख पढ़ें, फिर थोड़ा और गूगल करें, एक कप चाय / कॉफी / अंडरलाइन करें, अपने विचारों को समतल पर रखें और फिर अपना हेय-पे-ऐ बनाना शुरू करें।

सामान्य विचारधारा

REST * (1) क्या है?

REST "प्रतिनिधि राज्य स्थानांतरण" है, दूसरे शब्दों में, क्लाइंट के लिए सुविधाजनक प्रारूप में डेटा की प्रस्तुति, क्लाइंट द्वारा हम क्लाइंट से क्लाइंट सॉफ़्टवेयर का मतलब है <-> सर्वर मॉडल।

बदले में, HTTP प्रोटोकॉल और REST सिद्धांतों का उपयोग करके बनाई गई वेब सेवाओं को RESTful वेब सेवा कहा जाता है।

बिन बुलाए तुरंत एक सवाल हो सकता है: हमें ऐसी सेवाओं की आवश्यकता क्यों है? मुझे REST और OAuth तकनीकों पर आधारित एक सरल उदाहरण दें: आपके पास एक gmail खाता और एक ड्रॉपबॉक्स खाता है। ड्रॉपबॉक्स आपको प्रत्येक आमंत्रित दोस्त के लिए अतिरिक्त स्थान प्रदान करता है, हालांकि, मैन्युअल रूप से एक पत्र लिखना और जीमेल एड्रेस बुक से सभी पतों के माध्यम से सॉर्ट करना न केवल थकाऊ है, बल्कि लंबा भी है। ड्रॉपबॉक्स "आओ, दोस्त, मैं खुद से संपर्क आयात करता हूं और निमंत्रण भेजता हूं"। यह स्पष्ट है कि आप में से कोई भी मेलबॉक्स से ड्रॉपबॉक्स पर अपना पासवर्ड नहीं देना चाहेगा। यह वह जगह है जहाँ RESTful वेब सेवाओं का "जादू" खेल में आता है। API का उपयोग करते हुए (हे, लेकिन "एपीआई" नहीं, जैसा कि बहुत से लोग कहते हैं), ड्रॉपबॉक्स Google वेब सेवा के लिए अनुरोध करता है, फिर आपको Google प्राधिकरण पृष्ठ पर "भेजता है", इसलिए आप Google फॉर्म में अपना पासवर्ड दर्ज करते हैं , Google आपको प्राधिकृत करता है और आपको बता देता है कि एक्सेस बॉक्स (एक्सेस_टोकन) को ड्रॉपबॉक्स में दिए गए प्रक्रिया प्रक्रिया (प्रमाणीकरण) की सफलता के बारे में बताता है। अंत में, एक अद्वितीय टोकन (access_token) होना और इसे एपीआई में प्रत्येक अनुरोध के साथ संलग्न करना, ड्रॉपबॉक्स में आपके पासवर्ड के बारे में कुछ भी जाने बिना आपके व्यक्तिगत डेटा के साथ काम करने की क्षमता है।

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

CRUD

रेस्टफुल वेब सेवाओं को विकसित करते समय, सीआरयूडी * कार्यप्रणाली (2) को याद रखना महत्वपूर्ण है, जिसका डिक्रिप्टेड ट्रांसलेशन में अर्थ है: क्रिएट-रीड-मॉडिफाई-डिलीट (क्रिएट-रीड-अपडेट-डिलीट)।

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

पोस्ट - बनाएँ

प्राप्त करें - पढ़ें (पढ़ें, प्राप्त करें)

PUT - अपडेट (परिवर्तन, अद्यतन या बनाएं, अगर यह मौजूद नहीं है, तो कभी-कभी इसका उपयोग इस संस्करण में भी किया जाता है)

DELETE - हटाएं (हटाएं)

यह ध्यान दिया जाना चाहिए कि PUT और DELETE विधियों को लागू करना मुश्किल है, और ब्राउज़रों की सुविधाओं के कारण, इन विधियों को क्लाइंट-ब्राउज़र साइड पर AJAX के माध्यम से "मानवीय" रूप से लागू किया जा सकता है, और इसके अलावा यह सभी ब्राउज़रों में काम नहीं करता है। इसलिए, POST विधि के "अधिभार" के माध्यम से इन विधियों का उपयोग करने के लिए प्रथागत है। दूसरे शब्दों में: आप POST विधि के साथ किसी प्रकार के आरक्षित चर को भेज रहे हैं, उदाहरण के लिए: http_method, उस विधि के नाम के साथ जिसे आप ओवरलोड कर रहे हैं। POST + http_method = put - यह आपके सर्वर साइड को स्पष्ट करता है कि क्लाइंट ने संसाधन पर PUT का अनुरोध किया है।

KISS सिद्धांत जब रूटर के निर्माण

समझने KISS शुरू करने के लिए - यह छोटे और सरल रखने के लिए, जो लोग अभी तक साकार नहीं है - सरल और छोटी बातों के लिए छड़ी, दूसरे शब्दों में है कि यह सुलभ और हर किसी के लिए समझ में आता है और याद रखने में आसान है।

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

सबसे पहले, नियमों के मूल सेट को निर्धारित करें जो आपकी सेवा के अनुरूप है। उदाहरण के लिए, हमारी oDesk कंपनी में, हमने संकेत दिया कि URI, जिनका आधार / एपी है, RESTful API संसाधन हैं। यदि आप चाहें, तो आप इसे एक अलग उपडोमेन पर रख सकते हैं, यहां यह क्रॉस-ब्राउज़र क्वेरी और अन्य नुकसानों को याद रखने योग्य है, जिन्हें आप एनकाउंटर कर सकते हैं, यहां तक ​​कि "एक डोमेन" के अंदर भी।

अगला बिंदु एक संसाधन राउटर बनाना होगा - एक पता जहां आप डेटा तक पहुंच सकते हैं। हम कुछ बिंदुओं पर ध्यान देंगे जो एक पते को संकलित करते समय एक अच्छा तरीका माना जाता है:

- मुहावरेदार समूहों में टूट: एमसी - संदेश केंद्र संसाधन, टीम - कमांड संसाधन, आदि।

उदाहरण के लिए: / एपीआई / एमसी / ...

- संस्करण

उदाहरण के लिए: / एपीआई / एमसी / v1 / ...

- संसाधन का स्पष्ट नाम जिस तक पहुंच प्रदान की जाती है

उदाहरण के लिए: / api / mc / v1 / prefs / ... - संदेश केंद्र की सेटिंग तक पहुंच

- URL के अंतर्गत लगातार डेटा दर्ज करना

उदा .: / एपीआई / एमसी / वी / प्रीफ़्स / मायडेवलपर्सिड

- प्रतिक्रिया प्रारूप की परिभाषा: या तो रूटर यूआरएल के नाम पर, या "सिस्टम" चर में

उदाहरण के लिए: /api/mc/v1/prefs/mydevelopersuid.json - oDesk प्रत्यय ".json" का उपयोग करता है जब JSON प्रारूप में प्रतिक्रिया की आवश्यकता होती है, तो XML प्रारूप में xxml, आदि; / mc / v1 / Prefs / mydevelopersuid; tqx = out: json - यह वही है जो Google GDS में करता है; / api / json / mc / v1 / prefs / mydevelopersuid सिर्फ एक और संभावित विकल्प है, प्रारूप राउटर का हिस्सा है।

सबसे अच्छा अभ्यास

यहां आप बहुत सारी बातें कर सकते हैं और लंबे समय तक, मैं मुख्य बिंदुओं को सूचीबद्ध करूंगा:

- हमेशा json स्वरूप में प्रतिक्रिया प्राप्त करने की क्षमता प्रदान करें। ऐसा हुआ कि AJAX अनुप्रयोगों की दुनिया में, JSON * (3) क्लाइंट और सर्वर भागों के बीच डेटा स्थानांतरित करने के लिए वास्तविक तथ्य "मानक" बन गया है।

- प्राधिकरण के लिए सत्यापित और सिद्ध योजनाओं का उपयोग करें

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

- https के बारे में मत भूलो, जहां इसकी आवश्यकता है

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

- उत्तर में कभी भी "बाहर फेंका हुआ" कुछ न करें: आपके वेब सर्वर की त्रुटियां, वज़न, डेटाबेस के साथ समस्याएँ, आदि। यह सब आपके Restful वेब सर्वर द्वारा संसाधित किया जाना चाहिए और अनुरोधित प्रारूप में एक स्पष्ट जवाब देना चाहिए। दूसरे शब्दों में, क्लाइंट को जवाब देने में स्पष्ट त्रुटि प्रदान करें। प्रतिक्रिया स्वरूप और हेडर एक अलग विषय है। RFC 2616 * (4) के अनुसार सही HTTP स्टेटस को वापस करने के लिए अच्छा अभ्यास माना जाता है, और यदि स्टेटस आपको संदेश के मुख्य भाग को भेजने की अनुमति देता है, तो शरीर में एक छोटा संदेश है। कुछ लोग हमेशा शरीर के साथ "200 ओके" का दर्जा देना पसंद करते हैं, इसलिए ग्राहक को हमेशा संदेश को पार्स करना चाहिए और उसमें त्रुटि संदेश / टैग की उपस्थिति के लिए शरीर की जांच करनी चाहिए। अभी तक कोई स्पष्ट अभ्यास और सामान्य राय नहीं है!

- अपने एपीआई के लिए प्रलेखन लिखें, अन्यथा हे, पेशाब, यह बेकार है :)

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

पीआर

ODesk पर RESTful API का मुख्य डेवलपर होने के नाते (API - Developers.odesk.com PR है, इसे लें, इसे स्वास्थ्य के लिए उपयोग करें! :)) और लंबे समय तक REST सेवाएँ करने के बाद, मुझे लगता है कि इस क्षेत्र में बुनियादी ज्ञान साझा करना उचित था। मुझ पर विश्वास करना या न मानना ​​आपका व्यक्तिगत अधिकार है, लेकिन फिर भी मैं गहराई से आशा करता हूं कि हर कोई जो कम से कम थोड़ा पढ़ता है लेकिन अपने लिए लाभ प्राप्त करेगा, कम से कम अपने ज्ञान को ताज़ा करेगा;)



REST आर्किटेक्चर अभी भी बहुत सारे प्रश्न छोड़ता है और अक्सर होलीवार्स की ओर जाता है, अगर किसी तरह से मेरी राय आपके साथ नहीं बनती है तो मुझे दोष न दें।



PS लेख में केवल मूल पहलुओं को शामिल किया गया है और वेब सेवाओं के निर्माण के लिए विस्तृत निर्देश, एक पुस्तक आदि प्रदान करने के लिए शुद्ध नहीं है।

कड़ियाँ *

(1) http://en.wikipedia.org/wiki/Representational_State_Transfer

(२) http://en.wikipedia.org/wiki/Create,_read,_update_and_delete

(३) http://en.wikipedia.org/wiki/JSON

(४) http://www.w3.org/Protocols/rfc2616/rfc2616.html

संदर्भ: रेस्टफुल वेब सर्विसेज (लियोनार्ड रिचर्डसन, सैम रूबी), ओ'रेली मीडिया, इंक।

याहू रीस्ट समूह: http://tech.groups.yahoo.com/group/rest-discuss/