सार्वजनिक वेब API का versioning कैसे करें?

• जब सार्वजनिक वेब API में Product API जैसे नाम और /api/v1 path साथ में इस्तेमाल किए जाते हैं, तो API के semantic version और उसकी संरचना के बीच असंगति आ सकती है
• /v1/ path और major.minor.patch को साथ चलाने पर route और API contract आपस में मिल जाते हैं, और semantic version का पहला अंक URL में स्थिर हो जाता है
• backward compatibility तोड़ने वाले बदलावों के लिए नया path और reverse proxy route चाहिए होता है, जिससे contract की जानकारी URL और version number में बिखर सकती है
• अगर बाद की APIs एक साथ बनाई जाएँ, तो मौजूदा API व्यावहारिक रूप से v1 से बँध जाती है, और बाद में compatibility-breaking बदलावों में नाम और path का मतलब अस्पष्ट हो जाता है
• यह सार्वजनिक वेब API versioning में बार-बार खटकने वाले तरीकों और बेहतर design principles खोजने की समस्या-चेतना है

[GN⁺]

Lobste.rs की राय

• URL में /v1/ रखना वास्तव में बड़े फायदों में से एक है। क्योंकि endpoint बंद करने तक यह उपयोगकर्ताओं के लिए API को तोड़ने से बचाव को अनिवार्य करता है

• Evolving HTTP APIs और उसी लेखक की दूसरी पोस्टें उपयोगी सलाह देती हैं

• आम तौर पर हर route पर /v1/, /v2/ जैसा लगाकर breaking changes को दिखाते हैं। अगर यह कई hosts पर चलने वाले standard को define करने की जगह एक public operational API है, तो पूरी semantic versioning करने की खास वजह नहीं होती
  semantic versioning इसलिए होती है ताकि दूसरे developers changelog को 20 मिनट पढ़े बिना भी dependency को भरोसे के साथ upgrade कर सकें, लेकिन production API में लोग यह चुन नहीं सकते कि नया minor version या bugfix version वे कब अपनाएँगे
  क्या चीज़ breaking change है, इसे आम तौर पर documented behavior को बदलना, या documented behavior पर निर्भर मौजूदा clients को तोड़ना माना जाता है। कुछ जगह undocumented behavior में बदलाव को भी breaking मानती हैं, लेकिन उसमें जोखिम बहुत है

• Google में इसे ऐसे किया जाता है: AIP-185: API Versioning, AIP-180: Bacwards compatibility
  मुझे लगता है ये design docs Google के काम करने के तरीके के लिए काफी विशेष हैं, लेकिन API design करते समय मैंने इन्हें संदर्भ के रूप में इस्तेमाल किया है, और इनमें कुछ विचार बहुत उपयोगी रहे

• सामान्य रूप से मेरा मानना है कि हर API को breaking changes को जितना हो सके कम करने की कोशिश करनी चाहिए। उदाहरण के लिए, अगर आप property name बदलना चाहते हैं, तो पुरानी property हटाने के बजाय नया नाम साथ में duplicate करके जोड़ना बेहतर है
  हालांकि the people at Buttondown do it वाला तरीका भी साफ-सुथरा है। वे API versions के बीच migration define करते हैं, जिससे consumer header के ज़रिए अपनी API version को pin कर सकता है और provider लगातार बदलाव करता रह सकता है

  • output properties में property को duplicate करने का तरीका काफी अच्छा चला। लेकिन input में यह संभालना पड़ता है कि client दोनों properties को अलग-अलग values के साथ भेज दे
    पहली नज़र में जवाब लगता है, “नया नाम हमेशा प्राथमिक होगा”, लेकिन अगर client read-modify-write sequence कर रहा हो और server द्वारा बनाई गई object का modified version वापस भेज रहा हो, तो यह तरीका टूट सकता है। क्योंकि client सिर्फ पुरानी property अपडेट करके नई property को नज़रअंदाज़ करते हुए वैसा ही वापस भेज सकता है
  • जैसा API provider ने बताया, API versions के बीच migration देना अच्छा लगता है, लेकिन using an HTTP request header for versioning can cause problems
  • वह लिंक data shape को संभालने का तरीका बहुत अच्छी तरह समझाता है। लेकिन वह सिर्फ एक हिस्सा है; जब behavior खुद बदलता है तो क्या किया जाए, यह जानने की जिज्ञासा है
    लगता है ऐसे transformations को behavior mapping में भी इस्तेमाल किया जा सकता है, लेकिन अगर मैंने कुछ मिस नहीं किया है, तो उस हिस्से को वहाँ नहीं कवर किया गया

• आदर्श रूप से version को path में शामिल करना चाहिए, और नया version अतिरिक्त nature वाला होना चाहिए। तब पुराना version API ज़रूरी input/output transformations करके requests को नए API version की ओर reroute कर सकता है
  कुछ साल बाद जब कोई भी पुराना version इस्तेमाल न कर रहा हो, तो उसे हटाया जा सकता है और /v1/ path error बन जाएगा

• मैंने पहले Accept header के जरिए content negotiation से API versioning करने के बारे में थोड़ा पढ़ा था। अगर किसी ने इस तरह API versioning की है, तो उसका अनुभव जानना चाहूँगा
  मेरे अनुभव में resource-by-resource versioning या global versioning सबसे सहज तरीका लगा। deprecation के लिए Deprecation HTTP response header (RFC 9745) का उपयोग करना, और अंत में पुराने endpoints पर 410 Gone जैसा response लौटाना, clients को नए version पर ले जाने का एक समझदारी भरा तरीका लगता है
  साथ ही, यह भी सच में जानने की उत्सुकता है कि क्या किसी ने evolvable API बनाया है। यानी पुरानी version requests को अंदर ही अंदर नए API version requests में translate करना, और फिर client के migrate हो जाने या कुछ समय बीतने पर वास्तव में पुराने version को हटा देना