rest - एपीआई संस्करण के लिए सर्वोत्तम अभ्यास?




versioning (5)

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

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

क्या वेब सेवा रीस्ट एपीआई संस्करण के लिए कोई ज्ञात या सर्वोत्तम प्रथाएं हैं?

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


आरईएसटी एपीआई में कुछ जगहें आप वर्जनिंग कर सकते हैं:

  1. जैसा कि यूआरआई में उल्लेख किया गया है। यदि रीडायरेक्ट्स और जैसे अच्छी तरह से उपयोग किया जाता है तो यह ट्रैक्टेबल और यहां तक ​​कि एथेटिकली सुखदायक भी हो सकता है।

  2. स्वीकार करता है: हेडर, तो संस्करण फ़ाइल प्रकार में है। 'एमपी 3' बनाम 'एमपी 4' की तरह। यह भी काम करेगा, हालांकि आईएमओ यह थोड़ा सा अच्छी तरह से काम करता है ...

  3. संसाधन में ही। कई फ़ाइल स्वरूपों में उनके संस्करण संख्याएं एम्बेडेड होती हैं, आमतौर पर शीर्षलेख में; यह नए सॉफ्टवेयर को फ़ाइल प्रकार के सभी मौजूदा संस्करणों को समझकर 'बस काम' करने की इजाजत देता है, जबकि एक असमर्थित (नया) संस्करण निर्दिष्ट होने पर पुराना सॉफ़्टवेयर पंट कर सकता है। एक आरईएसटी एपीआई के संदर्भ में, इसका मतलब है कि आपके यूआरआई को कभी भी बदलना नहीं है, केवल आपके द्वारा दिए गए डेटा के विशेष संस्करण की प्रतिक्रिया।

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

  1. यदि आप 'क्लीन स्वीप' नए एपीआई करना चाहते हैं, या प्रमुख संस्करण परिवर्तनों के लिए जहां आप ऐसा दृष्टिकोण चाहते हैं।
  2. यदि आप क्लाइंट को जानना चाहते हैं कि इससे पहले कि यह काम करने जा रहा है या नहीं, तो PUT / POST करता है।
  3. अगर यह ठीक है तो क्लाइंट को अपना पुट / पोस्ट करना है यह पता लगाने के लिए कि क्या यह काम करने जा रहा है।

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

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

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

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

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

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

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

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

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

एपीआई रखरखाव के पीओवी से, स्रोत नियंत्रण प्रणालियों का उपयोग करके समानांतर में विभिन्न एपीआई संस्करणों को बनाए रखना आसान है जो मुख्य रूप से फाइलों (स्रोत कोड) संस्करण की सबसे छोटी इकाई के रूप में काम करते हैं।

हालांकि, यूआरआई में स्पष्ट रूप से दिखाई देने वाले एपीआई संस्करणों के साथ एक चेतावनी है: कोई भी इस दृष्टिकोण को ऑब्जेक्ट कर सकता है क्योंकि यूपीआई डिज़ाइन में एपीआई इतिहास दृश्यमान / अभिभावक हो जाता है और इसलिए आरईएसटी के दिशानिर्देशों के खिलाफ समय के साथ परिवर्तन की संभावना है । मैं सहमत हूँ!

इस उचित आपत्ति के आसपास जाने का तरीका, संस्करण रहित एपीआई बेस यूआरआई के तहत नवीनतम एपीआई संस्करण को कार्यान्वित करना है। इस मामले में, एपीआई क्लाइंट डेवलपर्स या तो चुन सकते हैं:

  • नवीनतम के खिलाफ विकसित करें (अपने आप को अंतिम एपीआई परिवर्तनों से बचाने वाले एप्लिकेशन को बनाए रखने के लिए प्रतिबद्ध करना जो उनके बुरी तरह से डिज़ाइन किए गए API क्लाइंट को तोड़ सकता है)।

  • एपीआई के एक विशिष्ट संस्करण से जुड़ें (जो स्पष्ट हो जाता है) लेकिन केवल सीमित समय के लिए

उदाहरण के लिए, यदि एपीआई v3.0 नवीनतम एपीआई संस्करण है, तो निम्नलिखित दो उपनाम होना चाहिए (यानी सभी एपीआई अनुरोधों के समान व्यवहार करें):

http://shonzilla/api/customers/1234
http://shonzilla/api/v3.0/customers/1234
http://shonzilla/api/v3/customers/1234

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

http://shonzilla/api/v2.2/customers/1234
http://shonzilla/api/v2.0/customers/1234
http://shonzilla/api/v2/customers/1234
http://shonzilla/api/v1.1/customers/1234
http://shonzilla/api/v1/customers/1234

30x HTTP स्टेटस कोडों में से किसी एक को वापस करना चाहिए जो पुनर्निर्देशन को इंगित करता है जिसका उपयोग Location HTTP शीर्षलेख के साथ किया जाता है जो संसाधन यूआरआई के उचित संस्करण पर रीडायरेक्ट करता है जो यह एक है:

http://shonzilla/api/customers/1234

कम से कम दो पुनर्निर्देशन HTTP स्थिति कोड हैं जो API संस्करण परिदृश्यों के लिए उपयुक्त हैं:

  • 301 स्थायी रूप से इंगित करता है कि अनुरोधित यूआरआई के साथ संसाधन स्थायी रूप से किसी अन्य यूआरआई में स्थानांतरित हो जाता है (जो एक संसाधन उदाहरण परमालिंक होना चाहिए जिसमें एपीआई संस्करण जानकारी नहीं है)। यह स्थिति कोड अप्रचलित / असमर्थित API संस्करण को इंगित करने के लिए उपयोग किया जा सकता है, जो एपीआई क्लाइंट को सूचित करता है कि एक संस्करण संसाधन संसाधन यूआरआई को संसाधन परमालिंक द्वारा प्रतिस्थापित किया गया है

  • 302 यह इंगित करता है कि अनुरोधित संसाधन अस्थायी रूप से किसी अन्य स्थान पर स्थित है, जबकि अनुरोध किया गया है कि यूआरआई अभी भी समर्थित हो। यह स्थिति कोड तब उपयोगी हो सकता है जब संस्करण-कम यूआरआई अस्थायी रूप से अनुपलब्ध हों और पुनर्निर्देशन पते का उपयोग करके अनुरोध दोहराया जाना चाहिए (उदाहरण के लिए एपीआई संस्करण के साथ यूआरआई को इंगित करना) और हम ग्राहकों को इसका उपयोग जारी रखने के लिए बताना चाहते हैं (यानी पर्मालिंक्स)।

  • अन्य परिदृश्य HTTP 1.1 विनिर्देश के पुनर्निर्देशन 3xx अध्याय में पाया जा सकता है


यूआरआई में अपना संस्करण रखें। एपीआई का एक संस्करण हमेशा दूसरे से प्रकारों का समर्थन नहीं करेगा, इसलिए तर्क है कि संसाधन केवल एक संस्करण से दूसरे संस्करण में माइग्रेट किए जाते हैं, यह सिर्फ सादा गलत है। यह XML से JSON तक प्रारूप स्विच करने जैसा नहीं है। प्रकार मौजूद नहीं हो सकते हैं, या वे अर्थात् बदल सकते हैं।

संस्करण संसाधन पते का हिस्सा हैं। आप एक एपीआई से दूसरे में रूटिंग कर रहे हैं। हेडर में एड्रेसिंग छुपाने के लिए यह बिल्कुल सही नहीं है।


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

पीछे की संगतता हमेशा के लिए रखना अक्सर लागत-निषिद्ध और / या बहुत मुश्किल है। हम बहिष्कार के उन्नत नोटिस, यहां सुझाए गए रीडायरेक्ट, डॉक्स और अन्य तंत्र जैसे रीडायरेक्ट देना पसंद करते हैं।





versioning