क्या किसी एपीआई में कभी संस्करण संख्या होनी चाहिए?

Question

मैं एक एपीआई बना रहा हूं जिसे मैं समय के साथ अपग्रेड करना चाहता हूं। क्या एपीआई में एक तर्क संख्या के रूप में संस्करण संख्या शामिल करना उचित है?

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

Answer 1

आप कर सकते हैं यह, यह बेहतर (IMHO) अगर तुम सिर्फ अपने एपीआई पीछे की ओर संगत हालांकि करते हैं। यह आम तौर पर आसान है, क्योंकि आपको संस्करण संख्या के आधार पर आपकी तरफ से शाखा की आवश्यकता नहीं है, आप बस दिए गए विधि को फिर से कार्यान्वित करें।

मुझे लगता है कि यह वास्तव में काफी कार्यान्वयन-विशिष्ट (और पर्यावरण-विशिष्ट) है। मैं जो भी आसान/बेहतर लगता हूं वह करूंगा।

मैं कहूंगा कि जब तक आप में कुछ फैशन में पीछे की संगतता बनाए रखते हैं, तो यह सब अच्छा है।

Answer 2

हाँ, उदाहरण Google Maps के लिए ले:

<script type="text/javascript"> 
    google.load("maps", "2"); 
</script> 

Answer 3

सबसे पहले, आप किस प्रकार का एपीआई मतलब रखते हैं - एक पुस्तकालय जो अनुप्रयोगों के खिलाफ लिंक करता है, या एक एक्सएमएल/आरपीसी एपीआई? मैं बाद में अपने जवाब में मानने जा रहा हूँ।

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

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

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

Answer 4

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

अधिक सामान्यतः "पारंपरिक" पुस्तकालयों के लिए किया (। जिन्हें आप अपने C/C++/नेट अनुप्रयोगों में से लिंक के रूप में) है:

• पुस्तकालय की संस्करण संख्या को लाने के लिए एक API प्रदान करते हैं । यह एप्लिकेशन को यह तय करने की अनुमति देता है कि उसे पुस्तकालय के नए/पुराने संस्करण की आवश्यकता है या नहीं।

• जितनी देर तक आप कर सकते हैं पीछे संगत हो।

• फ़ंक्शंस जोड़ें, उन्हें न बदलें। यदि आपको तर्क/इनपुट या व्यवहार बदलना है - तो एक नया फ़ंक्शन बनाएं, और पुराने को चारों ओर रखें।

• जब आपको अंततः पीछे की संगतता तोड़नी पड़ेगी और केवल पुराने संगत होने के लिए आसपास के सभी पुरानी क्रुफ्ट से छुटकारा पाना होगा, तो एक सौ संस्करण संस्करण है जो स्पष्ट रूप से असंगत संस्करणों को इंगित करता है।

Answer 5

सबसे पहले, यह जानने के बिना विशिष्ट होना मुश्किल है कि आपकी एपीआई किस भाषा के लिए है।

मुझे लगता है कि किसी ऑब्जेक्ट के निर्माण पर संस्करण संख्या को अनुमति देने के लिए स्वीकार्य होगा। ताकि आप ऑब्जेक्ट के विभिन्न संस्करणों के साथ अलग-अलग तरीकों के साथ संस्करण 1 या संस्करण 2 MyApi ऑब्जेक्ट बना सकें। संस्करण 2 एपीआई के साथ संस्करण 1 ऑब्जेक्ट्स बनाना अभी भी संभव होना चाहिए ताकि लाइब्रेरी के उपयोगकर्ता धीरे-धीरे अपग्रेड कर सकें।

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

Answer 6

हाँ यह बहुत समझदार है, खासकर यदि आप marshalling/unmarshalling और interfaces (COM/CORBA/SOAP) पर निर्मित सिस्टम का उपयोग कर रहे हैं। यह मोनोलिथिक अनुप्रयोगों में भी उपयोगी है।

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

संपादित करें: आप (कम भाषाओं का समर्थन)

Answer 7

मैं कई एपीआई कि संस्करण किसी तरह का समर्थन करते हैं, सबसे विशेष रूप से ODBC का उपयोग किया है Apache Thrift (कम प्रलेखित) डाटा इंटरचेंज के लिए, या Protocol Buffers को देखने के लिए चाहते हो सकता है । API कॉल स्तर पर इन की अनुमति संस्करण में से कोई भी - वे सभी आप पुस्तकालय जो संस्करण आप एक एक बंद आधार पर के साथ काम करना चाहता था बताने के लिए आवश्यक - कुछ की तरह:

MyAPI::UseVesion(2, 1); 

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

MyAPI::Handle h = MyAPI::GeHandle(2, 1); // get 2.1 version of handle 
MyAPI::UseHandle(3, 0, h);     // use it somehow with a 3.0 function 

आप संकलन समय पर बेमेल पहचान नहीं कर सकता है, और यह या चलाने के समय में काम नहीं हो सकता है। Yechh!

Answer 8

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

प्रत्येक संस्करण के लिए एक अलग इंटरफ़ेस का उपयोग करें और इसे रिलीज़ होने के बाद इसे कभी भी न बदलें।

इससे पीछे की संगतता बहुत आसान हो जाती है।

Answer 9

एक चीज जो आप करना चाहते हैं वह उन कार्यों को प्रदान करना है जो संस्करण संख्याएं लेते हैं और उन्हें समझते हैं।

def has_extended_key_format(version): 
    return version > 3 

या: की तरह कार्य

#define HAS_EXTENDED_KEY_FORMAT(version) ((version) > 3) 

(। हाँ, C और C++ के लिए #define उपयोग करते हैं, तो पूर्वप्रक्रमक संकलन समय पर संस्करण के आधार पर कर सकते हैं)

इस तरह, आपका कोड आपके संस्करण चेक में जादू संख्याओं से भरा नहीं है, और लोग आपका कोड पढ़ सकते हैं और जान सकते हैं कि आप वास्तव में किस सुविधा की जांच कर रहे हैं।