वर्जन रीस्ट एपीआई। प्रत्येक एपीआई का अपना संस्करण होता है

Question

URL के REST API के संस्करण को निर्दिष्ट करना बहुत आम है, विशेष रूप से पथ की शुरुआत में, जैसे कुछ:

POST /api/v1/accounts
GET /api/v1/accounts/details

हालाँकि, मैंने ऐसा कोई डिज़ाइन नहीं देखा है जहाँ संस्करण प्रत्येक API से संबद्ध हो। दूसरे शब्दों में, हम प्रत्येक एपीआई के संस्करण को अलग-अलग बनाए रखते हैं। अर्थात:

POST /api/accounts/v2
GET /api/accounts/details/v3

इस दृष्टिकोण का उपयोग करते हुए हम विशिष्ट एपीआई के एपीआई संस्करण को बढ़ाते हैं जब ब्रेकिंग परिवर्तन की आवश्यकता होती है, पूरे एपीआई के संस्करण को बढ़ाने की आवश्यकता नहीं होती है।

आम शैली के बजाय इस शैली का उपयोग करने की कमियां क्या हैं?

Answer 1

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

आपका प्रश्न उस संदर्भ में समझ में आता है, जहां REST API पैकेज के संसाधन मॉड्यूलर हैं और इसलिए संभावित रूप से विकसित और अलग-अलग संस्करणित किए गए हैं।

फिर, जहां तक ​​मैं देख रहा हूं, आपके प्रस्तावित संसाधन लोकेटर का नामकरण सम्मेलन की मुख्य सहमति है:

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

एपीआई का निर्माण करते समय, आपका एक मुख्य उद्देश्य इसे उपयोग करना आसान बना रहा है ...

आप शायद एक HTTP हेडर के साथ एक ब्रेकिंग बदलाव या यहां तक ​​कि REST एपीआई को शुरू करने के लिए एक बेहतर तरीका खोज सकते हैं?

HTTP हेडर दृष्टिकोण के बारे में थोड़ा और जानने के लिए, नीचे दिए गए अन्य उत्तर देखें: और https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

Answer 2

यहाँ एक और भी बेहतर तरीका है: का उपयोग सामग्री बातचीत के साथ अपने एपीआई संस्करण के लिए Content-Typeऔर Acceptहेडर:

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

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

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

Comments

ओम को स्वीकार करने वाले हेडर को संस्करण सिग्नलिंग का सबसे खराब विकल्प होना चाहिए। यदि आप कर सकते हैं, तो एक वर्जन हैडर का उपयोग करें, यदि आप (यानी AWS मार्ग) उर मार्ग का उपयोग कर सकते हैं

— Ewan

@ इवान क्यों? एक कस्टम संस्करण हेडर का अर्थ है कि बिचौलियों को सूचित किए बिना विभिन्न संस्करण समान संसाधन हैं कि सामग्री भिन्न हो सकती है। एक कैशिंग प्रॉक्सी v2 अनुरोधों के लिए v1 कैश्ड प्रतिक्रियाओं की सेवा नहीं करने के लिए अपने हेडर का उपयोग करना नहीं जानता।

— जैक

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

— इवान

@ ईवान यह है कि किस प्रकार और किस प्रकार vndके +सिंटैक्स निम्न हैं: यह इंगित करने के लिए कि यह प्रकार का एक विक्रेता-विशिष्ट उप- application/jsonप्रकार है। यह वही है जो सामग्री प्रकार के लिए डिज़ाइन किया गया है। आपका संसाधन कई प्रारूपों में उपलब्ध है। आप ग्राहक से पूछ रहे हैं कि उन्हें कौन सा प्रारूप चुनना है। इसके अतिरिक्त, कोई कारण नहीं है एपीआई अनुरोध मानक HTTP कैशिंग शब्दार्थ का उपयोग नहीं कर सकते हैं।

— जैक

यदि आप myapi v2 में बग को ठीक करते हैं तो आप एक नया माइम प्रकार नहीं लौटा रहे हैं।

— इवान

Answer 3

महत्वपूर्ण बात यह है कि यदि आप प्रत्येक समापन बिंदु को अलग से संस्करणित करते हैं तो आपको प्रत्येक समापन बिंदु को अलग से परिनियोजित करने में सक्षम होना चाहिए।

एपीआई में आम तौर पर एक संस्करण होता है क्योंकि सभी अंत बिंदु एक ही कोडबेस में होते हैं और इस प्रकार साझा निर्भरताएं होती हैं और एक साथ तैनात होती हैं।

यदि आप बदलाव करते समय संस्करण को अपडेट नहीं कर रहे हैं, क्योंकि "ओह, मुझे पूरा यकीन है कि मेरा परिवर्तन प्रभावित नहीं करता है" जब आप गलती करते हैं तो आप मुसीबत में पड़ जाएंगे।

इसके अतिरिक्त, आप अपने एपीआई के v1 और v2 दोनों को एक ही समय पर तैनात करना चाहेंगे। यह आमतौर पर प्रत्येक संस्करण को एक अलग सर्वर पर तैनात करने और तदनुसार ट्रैफ़िक को रूट करने के द्वारा किया जाता है।

यदि आपके पास कोई एकल API संस्करण नहीं है, तो यह बहुत अधिक जटिल हो जाता है।