🧑🏿‍🤝‍🧑🏼 💃🏾 👩🏿‍🤝‍👩🏼 सर्वर के लिए RESTful API

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

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

दर्शकों को लक्षित करें

यह पोस्ट उन लोगों के लिए है जिनके पास उन्नत RESTful API के माध्यम को विकसित करने में ज्ञान है। साथ ही जावा / रूबी / स्काला जैसी सर्वर भाषाओं में ऑब्जेक्ट-ओरिएंटेड (या कार्यात्मक) प्रोग्रामिंग के कुछ बुनियादी ज्ञान। (मैंने जानबूझकर PHP या प्रोग्राम हाइपरलिंकड पास्ता को नजरअंदाज किया)।
लगभग। ट्रांस। यहां लेखक ने प्रोग्रामिंग भाषाओं के इतिहास पर एक आधा-मजाक वाले लेख का लिंक प्रदान किया जहां PHP को प्रोग्रामेबल हाइपरलिंकड पास्ता (प्रोग्रामेबल हाइपरलिंक नूडल्स) के रूप में डिक्रिप्ट किया गया था। PHP में लेखक के रवैये की क्या विशेषता होगी?

लेख की संरचना और संगठन

लेख काफी विस्तृत है और इसमें दो भाग हैं। पहला REST की मूल बातों का वर्णन करता है, जबकि दूसरा आपके API के विभिन्न संस्करणों के प्रलेखन और समर्थन का वर्णन करता है। शुरुआती के लिए पहला भाग, पेशेवरों के लिए दूसरा। मुझे इसमें कोई संदेह नहीं है कि आप एक समर्थक हैं, और इसलिए आपके लिए "दस्तावेज़ एपीआई" अध्याय में सीधे कूदने के लिए एक लिंक है । शायद आपको वहां से शुरू करना चाहिए, अगर यह आपको लगता है कि यह पोस्ट "कई बुक्का, निसिलिल ..." की श्रेणी से आती है।

श्रेष्ठ सिद्धांत

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

राज्य की परवाह किए बिना (statelessness)

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

आइए कल्पना करें कि आपके पास न्यू फेसबुक नामक एक स्टार्टअप है। एक अच्छा उदाहरण जहां एक डेवलपर एक गलती कर सकता है वह एक एपीआई कॉल प्रदान करता है जो मोबाइल डिवाइस को स्ट्रीम में अंतिम रीड आइटम सेट करने की अनुमति देता है (चलो इसे फेसबुक फीड कहते हैं)। एक एपीआई कॉल जो आमतौर पर एक फ़ीड लौटाता है (इसे कॉल / फ़ीड कहते हैं) अब उन तत्वों को वापस करेगा जो सेट एक से नए हैं। स्मार्ट लगता है, है ना? क्या आपने क्लाइंट और सर्वर के बीच डेटा विनिमय "अनुकूलित" किया है? लेकिन नहीं।

इस मामले में क्या गलत हो सकता है कि यदि आपका उपयोगकर्ता दो या तीन उपकरणों से सेवा का उपयोग करता है, तो जब उनमें से एक अंतिम रीड आइटम स्थापित करता है, तो बाकी अन्य डिवाइस पर पढ़े गए फ़ीड आइटम लोड नहीं कर पाएंगे। पहले से।

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

इस कॉल को ऑप्टिमाइज़ करने का सही तरीका उस समय को पास करना है जब अंतिम रीड टेप प्रविष्टि एपीआई कॉल के तर्क के रूप में बनाई गई थी जो फ़ीड (/ फ़ीड? LastFeed = 20120228) लौटाता है। एक और, अधिक "सही" विधि है - अगर-संशोधित-HTTP HTTP हेडर का उपयोग करके। लेकिन हम अभी तक इस दिशा में गहराई में नहीं जाएंगे। हम दूसरे भाग में इस पर चर्चा करेंगे।

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

कैचएबल और स्तरित वास्तुकला

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

क्लाइंट - सर्वर विभाजन और एक एकल इंटरफ़ेस

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

RESTful सर्वर के विकास के दौरान पालन करने के लिए ये संभवतः तीन सबसे महत्वपूर्ण सिद्धांत हैं। नीचे तीन महत्वपूर्ण सिद्धांतों का वर्णन किया जाएगा, लेकिन वे सभी सीधे संबंधित हैं जो हम यहां बात कर रहे हैं।

अन्य अनुरोध और चार HTTP तरीके

प्राप्त
पोस्ट
PUT
हटाएँ

"कैचेबिलिटी" और GET अनुरोधों का सिद्धांत

याद रखने वाली मुख्य बात यह है कि जीईटी के माध्यम से की गई कॉल सर्वर की स्थिति को नहीं बदलना चाहिए। बदले में इसका मतलब है कि आपके अनुरोधों को किसी भी मध्यवर्ती प्रॉक्सी (लोड में कमी) द्वारा कैश किया जा सकता है। इस प्रकार, आप, सर्वर डेवलपर के रूप में, अपने डेटाबेस में डेटा को संशोधित करने वाली जीईटी विधियों को प्रकाशित नहीं करना चाहिए। यह रेस्टफुल दर्शन का उल्लंघन करता है, विशेष रूप से ऊपर वर्णित दूसरा बिंदु। आपके GET कॉल को "अंतिम लॉग इन" जैसे access.log या अपडेट डेटा में प्रविष्टियों को भी नहीं छोड़ना चाहिए। यदि आप डेटाबेस में डेटा बदलते हैं, तो यह POST / PUT विधियाँ होनी चाहिए।

POST बनाम PUT की वही चर्चा

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

String userId = this.request["USER_ID"];

यहां तक कि अगर यह ऑपरेशन दो या तीन बार किया जाता है, तो कोई नुकसान नहीं होगा (अतिरिक्त प्रोसेसर चक्र को छोड़कर)। दूसरी ओर, POST, बेरोजगार नहीं है। यह थोड़ा बढ़ा हुआ है। आपको POST या PUT का उपयोग करना चाहिए, इस बात पर विचार करते हुए कि प्रदर्शन किया जा रहा है या नहीं, यह बेकार है। प्रोग्रामर की भाषा में, यदि क्लाइंट को बनाई जाने वाली वस्तु का URL पता है, तो PUT का उपयोग करें। यदि क्लाइंट वांछित ऑब्जेक्ट बनाने वाले विधि / वर्ग के URL को जानता है, तो POST का उपयोग करें।

 PUT www.example.com/post/1234

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

 POST www.example.com/createpost

POST का उपयोग करें यदि सर्वर स्वयं एक विशिष्ट पहचानकर्ता बनाता है और इसे क्लाइंट को लौटाता है। यदि यह अनुरोध बाद में समान मापदंडों के साथ दोहराया जाता है तो डुप्लिकेट रिकॉर्ड बनाए जाएंगे।
इस चर्चा में अधिक जानकारी।

DELETE विधि

DELETE बिलकुल अनोखा है। यह PUT की तरह ही है, और यदि कोई मौजूद है, तो रिकॉर्ड को हटाने के लिए इसका उपयोग किया जाना चाहिए।

बाकी जवाब

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

प्रमाणीकरण

प्रमाणीकरण https के माध्यम से किया जाना चाहिए और ग्राहक को कूटबद्ध रूप में पासवर्ड भेजना होगा। ऑब्जेक्टिव-सी में NSString हैश के sha1 प्राप्त करने की प्रक्रिया काफी स्पष्ट और सरल है, और उपरोक्त कोड स्पष्ट रूप से यह दर्शाता है।

 - (NSString *) sha1 { const char *cstr = [self cStringUsingEncoding:NSUTF8StringEncoding]; NSData *data = [NSData dataWithBytes:cstr length:self.length]; uint8_t digest[CC_SHA1_DIGEST_LENGTH]; CC_SHA1(data.bytes, data.length, digest); NSMutableString* output = [NSMutableString stringWithCapacity:CC_SHA1_DIGEST_LENGTH * 2]; for(int i = 0; i <; CC_SHA1_DIGEST_LENGTH; i++) [output appendFormat:@"%02x", digest[i]]; return output; }

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

RFC 2617 एक HTTP सर्वर पर प्रमाणीकरण के दो तरीकों का वर्णन करता है। पहला है बेसिक एक्सेस, दूसरा है डाइजेस्ट। मोबाइल ग्राहकों के लिए, इन दोनों विधियों में से कोई भी उपयुक्त है और अधिकांश सर्वर (और क्लाइंट भी) भाषाओं में ऐसी प्रमाणीकरण योजनाओं को लागू करने के लिए अंतर्निहित तंत्र हैं।

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

फेसबुक ग्राफ एपीआई इस समय oAuth का सबसे विकसित और व्यापक कार्यान्वयन है। OAuth का उपयोग करते हुए, फेसबुक उपयोगकर्ता अन्य निजी और पहचान जानकारी (उपयोगकर्ता नाम / पासवर्ड) प्रकाशित किए बिना अपनी तस्वीरों को तीसरे पक्ष के अनुप्रयोगों के साथ साझा कर सकते हैं। उपयोगकर्ता अपना पासवर्ड बदलने के बिना अवांछित एप्लिकेशन तक पहुंच को प्रतिबंधित कर सकता है।

अब तक, मैंने REST की मूल बातों के बारे में बात की। अब हम लेख के सार की ओर मुड़ते हैं। निम्नलिखित अध्यायों में, मैं उन व्यावहारिक तरीकों के बारे में बात करूँगा जिनका उपयोग दस्तावेज बनाते समय, नए बनाने और मेरे एपीआई के पुराने संस्करणों के लिए समर्थन पूरा करने के लिए किया जाना चाहिए ...

एपीआई प्रलेखन

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

प्रलेखन

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

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

दस्तावेज़ीकरण क्वेरी पैरामीटर

मान लें कि आपके पास एक एपीआई है जो एक उपयोगकर्ता को फेसबोक टोकन का उपयोग करके लॉग इन करने की अनुमति देता है। इस तरीके को कॉल करें / लॉगिन करें।

 Request /login Headers Authorization: Token XXXXX User-Agent: MyGreatApp/1.0 Accept: application/json Accept-Encoding: compress, gzip Parameters Encoding type – application/x-www-form-urlencoded token – “Facebook Auth Token” (mandatory) profileInfo = “json string containing public profile information from Facebook” (optional)

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

प्रतिक्रिया विकल्प का दस्तावेजीकरण

एपीआई कॉल के लिए प्रतिक्रियाओं को भी उच्च-स्तरीय वस्तुओं के मॉडल के आधार पर प्रलेखित किया जाना चाहिए। एक ही चौके के उदाहरण का हवाला देते हुए, / स्थान / # आयोजन स्थल # विधि को कॉल करने से घटना के स्थान का वर्णन करने वाला एक डेटा संरचना (मॉडल) वापस आ जाएगा।

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

नए बनाने के कारण और अपने एपीआई के पुराने संस्करणों का समर्थन करना बंद करें

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

संस्करण का पृथक्करण

अपने सर्वर कोड को अलग-अलग फ़ोल्डर्स में तैनात करना और कॉल के लिए अलग URL का उपयोग करने का मतलब यह नहीं है कि आपने अपने API को सफलतापूर्वक संस्करणों में विभाजित कर लिया है।
इसलिए example.com/api/v1 का उपयोग एप्लिकेशन के संस्करण 1.0 द्वारा किया जाएगा, और आपका सबसे ताज़ा और सबसे अच्छा संस्करण 2.0 उदाहरण का उपयोग करेगा ।.com/i_v2

जब आप अपडेट करते हैं, तो आप लगभग हमेशा आंतरिक डेटा संरचनाओं और मॉडल में परिवर्तन करते हैं। इसमें डेटाबेस में परिवर्तन (कॉलम जोड़ना या निकालना) शामिल हैं। बेहतर समझ के लिए, आइए कल्पना करें कि आपके "नए फ़ेसबुक" में एक एपीआई कॉल / फ़ीड है, जो "फ़ीड" ऑब्जेक्ट देता है। आज, संस्करण 1 में, आपके "रिबन" ऑब्जेक्ट में उपयोगकर्ता अवतार URL (avatarURL), उपयोगकर्ता नाम (personName), पोस्ट टेक्स्ट (feedEntryText) और पोस्ट निर्माण समय (टाइमस्टैम्प) शामिल हैं। बाद में, संस्करण 2 में, आप एक नई सुविधा प्रस्तुत करते हैं जो विज्ञापनदाताओं को फ़ीड में अपने उत्पादों के विवरण पोस्ट करने की अनुमति देता है। अब "रिबन" ऑब्जेक्ट में, मान लें कि एक नया फ़ील्ड "sourceName" है, जो रिबन प्रदर्शित होने पर उपयोगकर्ता नाम को ओवरलैप करता है। इसलिए, एप्लिकेशन को "personName" के बजाय "sourceName" प्रदर्शित करना चाहिए। चूंकि एप्लिकेशन को अब "personName" प्रदर्शित करने की आवश्यकता नहीं है अगर "sourceName" निर्दिष्ट है, तो आप "personName" भेजने का निर्णय नहीं लेते हैं यदि "sourceName" है। यह सब तब तक अच्छा लगता है जब तक कि आपके एप्लिकेशन का पुराना संस्करण, संस्करण 1, अपडेट किए गए सर्वर तक नहीं पहुंच जाता। यह बिना किसी शीर्षक के फ़ीड से आपकी विज्ञापन प्रविष्टियाँ प्रदर्शित करेगा क्योंकि "personName" गायब है। इस तरह की समस्या को हल करने का एक "सक्षम" तरीका "व्यक्तिनाम" और "स्रोतनाम" दोनों को भेजना है। लेकिन, दोस्तों, जीवन हमेशा इतना सरल नहीं होता है। एक डेवलपर के रूप में, आप अपने डेटा में प्रत्येक डेटा मॉडल के साथ किए गए सभी एकल परिवर्तनों को ट्रैक करने में सक्षम नहीं होंगे। यह परिवर्तन करने का एक बहुत प्रभावी तरीका नहीं है क्योंकि आधे साल के बाद आप लगभग भूल जाएंगे कि आपके कोड में कुछ क्यों और कैसे जोड़ा गया है।

वेब 2.0 पर वापस लौटना, यह कोई समस्या नहीं थी। एपीआई में परिवर्तन का समर्थन करने के लिए जावास्क्रिप्ट क्लाइंट को तुरंत संशोधित किया गया था। हालाँकि, इंस्टॉल किए गए iOS एप्लिकेशन अब आप पर निर्भर नहीं हैं। अब उन्हें अपडेट करना उपयोगकर्ता का विशेषाधिकार है।

मेरे पास इस तरह की मुश्किल स्थितियों के लिए एक सुंदर समाधान है।

URL संस्करण प्रतिमान

पहला समाधान URL जुदाई है।
api.example.com/v1/feeds iOS एप्लिकेशन के संस्करण 1 द्वारा उपयोग किया जाएगा
api.example.com/v2/feeds का उपयोग संस्करण 2 द्वारा किया जाएगा।
इस तथ्य के बावजूद कि यह अच्छा लगता है, आप दिए गए डेटा के प्रारूप में प्रत्येक परिवर्तन के लिए अपने सर्वर कोड की प्रतियां बनाना जारी नहीं रख पाएंगे। मैं केवल एपीआई में वैश्विक परिवर्तन के मामले में इस दृष्टिकोण का उपयोग करने की सलाह देता हूं।

मॉडल के माध्यम से संस्करण प्रतिमान

ऊपर, मैंने दिखाया कि आपके डेटा संरचनाओं (मॉडल) को कैसे दस्तावेज़ किया जाए। सर्वर और क्लाइंट भागों के डेवलपर्स के बीच एक अनुबंध के रूप में इस प्रलेखन पर विचार करें। आपको संस्करण को बदले बिना मॉडल में बदलाव नहीं करना चाहिए। इसका मतलब यह है कि पिछले मामले में दो मॉडल फीड 1 और फीड 2 होने चाहिए।

Feed2 में एक sourceName फ़ील्ड है और यह sourceName सेट होने पर personName के बजाय sourceName लौटाता है। प्रलेखन में निर्दिष्ट के रूप में फीड 1 का व्यवहार वैसा ही रहता है। नियंत्रक का एल्गोरिदम कुछ इस तरह होगा:

आपको फैक्ट्री मेथड पैटर्न के अनुसार क्लास को अलग क्लास में ले जाने के लिए तर्क को आगे बढ़ाना चाहिए। संबंधित नियंत्रक कोड कुछ इस तरह दिखना चाहिए:

 Feed myFeedObject = Feed.createFeedObject("1.0"); myFeedObject.populateWithDBObject(FeedDao* feedDaoObject);

जहां उपयोग किए गए एपीआई के संस्करण पर निर्णय उपयोगकर्ता द्वारा अनुरोध पाठ के उपयोगकर्ता क्षेत्र के अनुसार किया जाएगा।

पूरक:
UserAgent स्ट्रिंग से संस्करण संख्या का उपयोग करने के बजाय, स्वीकार शीर्षलेख में संस्करण संख्या का उपयोग करना बेहतर होगा। इसलिए भेजने के बजाय

 Accept: application/json

भेजा जाना चाहिए

 Accept: application/myservice.1.0+json

इस प्रकार, आप REST सर्वर के लिए प्रत्येक अनुरोध के लिए एपीआई के संस्करण को निर्दिष्ट करने में सक्षम होंगे। इस टिप के लिए हैकर समाचार पाठकों को धन्यवाद।

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

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

समर्थन की समाप्ति

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

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

कैशिंग

प्रदर्शन के संबंध में एक और महत्वपूर्ण बिंदु जिसे आपको ध्यान देना चाहिए वह है कैशिंग। यदि आपको लगता है कि यह क्लाइंट एप्लिकेशन का कार्य है, तो ध्यान से सोचें। इस लेख के भाग 2 में, मैं वर्णन करूँगा कि http 1.1 का उपयोग करके कैशिंग को कैसे व्यवस्थित किया जाए।

आपके API की हैंडलिंग और अंतर्राष्ट्रीयकरण में त्रुटि

ग्राहक को उसकी घटना के मामले में त्रुटि का कारण लाना सही डेटा भेजने से कम महत्वपूर्ण नहीं है। मैं इस लेख के भाग 3 में त्रुटि से निपटने और अंतर्राष्ट्रीयकरण के बारे में बात करूंगा। मैं कुछ भी वादा नहीं करूंगा, किसी भी मामले में, लिखने में समय लगेगा।

अनुवादक से:
मैं खुद iOS के लिए डेवलपर नहीं हूं और वेब सेवाओं को विकसित नहीं किया है, इस क्षेत्र में मेरे स्तर का वर्णन किया जा सकता है "मैं एक शुरुआती बनने जा रहा हूं।" लेकिन विषय मेरे लिए दिलचस्प है और मुझे लेख पसंद आया, और इतना कि मैंने इसका अनुवाद करने का फैसला किया।

दूसरा भाग

सर्वर के लिए RESTful API - इसे सही करना (भाग 1)