वर्शन और संगतता

API का एक मेजर वर्शन है, /v1, और वह सिर्फ़ बढ़ता है। आज लिखा गया इंटीग्रेशन नए फ़ीचर आने पर भी काम करता रहता है: जिस चीज़ पर वह निर्भर है, उसका न नाम बदलता है, न उसे हटाया जाता है, न उसे नया मतलब दिया जाता है।

वर्शन नंबर

API का वर्शन नंबर 1.62.0 जैसा होता है। यह हर रिलीज़ के साथ बदलता है:

माइनर नंबर, जब कुछ जोड़ा जाता है: एंडपॉइंट, फ़ील्ड, इवेंट;
पैच नंबर, जब कोई विवरण या संदेश का टेक्स्ट ठीक किया जाता है और कुछ और नहीं बदलता।

किसी पते पर चल रहा वर्शन आप कभी भी पढ़ सकते हैं:

कहाँ	क्या
`GET /openapi.json`	स्पेसिफ़िकेशन का `info.version`
इवेंट फ़ीड का हर इवेंट और हर वेबहुक	`api_version`, वह वर्शन जिसके स्कीमा का `data` पालन करता है

GET /v1/health में भी version होता है, पर यह उस Sursa रिलीज़ का वर्शन है, जो इस पते को सर्व करती है, API का वर्शन नहीं।

माइनर वर्शन आप नहीं चुनते: हर रिक्वेस्ट मौजूदा वर्शन पर चलती है। नीचे के नियमों की वजह से यह सुरक्षित है।

/v1 में क्या बदल सकता है

ये बदलाव किसी भी माइनर वर्शन में आ सकते हैं। अपना इंटीग्रेशन ऐसे लिखें कि ये उसे न तोड़ें:

नए एंडपॉइंट।
नए वैकल्पिक पैरामीटर और रिक्वेस्ट फ़ील्ड। इनके बिना रिक्वेस्ट पहले जैसा ही व्यवहार करती हैं।
रिस्पॉन्स, ऑब्जेक्ट और इवेंट में नए फ़ील्ड।
रिस्पॉन्स में enum सूचियों के नए मान, जैसे कार्ड का नया स्टेटस या नया इवेंट टाइप।
नए एरर कोड, और नए रिस्पॉन्स हेडर।
कम सख़्त होने वाली सीमाएँ: ज़्यादा अधिकतम लंबाई, ज़्यादा चौड़ी रेंज।
एरर के message टेक्स्ट और विवरणों के बदले हुए शब्द।

आपके कोड को क्या सहना चाहिए

अनजान फ़ील्ड को नज़रअंदाज़ करें। जब रिस्पॉन्स में उम्मीद से ज़्यादा फ़ील्ड हों, तो असफल न हों, और ऐसे सख़्त स्कीमा इस्तेमाल न करें, जो उन्हें अस्वीकार कर दें।
अनजान enum मान स्वीकार करें। रिस्पॉन्स की हर enum सूची बढ़ सकती है। अनजान मान को एरर के बजाय “अन्य” मानें।
अनजान इवेंट टाइप छोड़ दें, वेबहुक में भी और स्ट्रीम में भी।
अनजान एरर कोड को उनके HTTP स्टेटस से संभालें: देखें एरर।
JSON ऑब्जेक्ट में फ़ील्ड के क्रम पर निर्भर न रहें, और न ही संदेशों के सटीक टेक्स्ट पर।

/v1 में क्या कभी नहीं बदलता

पाथ, पैरामीटर, फ़ील्ड या enum मान का नाम कभी नहीं बदलता, और उसे कभी हटाया नहीं जाता।
फ़ील्ड का टाइप कभी नहीं बदलता, और फ़ील्ड को कभी नया मतलब नहीं मिलता, जैसे नई इकाइयाँ।
आज स्वीकार की जाने वाली रिक्वेस्ट बाद में अस्वीकार नहीं की जाती।
सफल रिस्पॉन्स का स्टेटस कोड वही रहता है।
एरर कोड का मतलब वही रहता है, और एरर रिस्पॉन्स के detail फ़ील्ड का रूप वही रहता है।
इवेंट टाइप का नाम कभी नहीं बदलता और उन्हें हटाया नहीं जाता, और उनके data में सिर्फ़ फ़ील्ड जुड़ते हैं।

ब्रेकिंग बदलाव

अगर कभी असंगत बदलाव की ज़रूरत पड़ी, तो वह नए मेजर वर्शन के रूप में, जैसे /v2, /v1 के बगल में रिलीज़ होगा। /v1 बिना बदलाव के काम करता रहता है, और दोनों साथ-साथ चलते हैं।

जब किसी रूट को बंद करना होता है:

स्पेसिफ़िकेशन में उसे deprecated चिह्नित किया जाता है और चेंजलॉग में उस तारीख़ के साथ दिया जाता है, जब वह बंद होगा।
उसके रिस्पॉन्स में Deprecation: true और Sunset: <date> हेडर होते हैं।
वह घोषणा के बाद कम से कम 180 दिन तक काम करता रहता है। जिन संगठनों की API कुंजियाँ उसे इस्तेमाल करती हैं, उन्हें कम से कम 90 दिन पहले लिखित में बताया जाता है।
सनसेट तारीख़ के बाद वह 90 दिन और कोड api.gone के साथ 410 से जवाब देता है।

अपने लॉग या मॉनिटरिंग में Deprecation हेडर पर नज़र रखें: यह सबसे पहला संकेत है कि आपका इस्तेमाल किया जाने वाला रूट हटने वाला है।

जानकारी रखना

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