एपीआई वर्शनिंग रणनीतियाँ

मुझे वर्शनिंग की आवश्यकता क्यों है?

एपीआई ग्राहकों की तुलना में तेजी से बदलता है। संस्करण आपको एकीकरण को तोड़ ने के बिना सुविधाओं को जारी करने और त्रुटियों को संपादित करने की अनुमति देता है, परिवर्तन की रस्म निर्धारित करता है और विकास को पूर्वानुमानित करता है। कुंजी: डिफ़ॉल्ट योजक परिवर्तन, बड़ी - केवल टूटने के लिए, स्वचालित संगतता जांच और विचारशील सूर्यास्त नीति।

मूल सिद्धांत

1. योगात्मक-पहला: नए वैकल्पिक क्षेत्र/विधियाँ/घटनाएँ - ठीक है; विलोपन और अर्थ परिवर्तन - प्रमुख।

2. एमजीसी (न्यूनतम वारंटी अनुबंध) स्थिर है; संवर्धन - क्षमताओं के माध्यम से/'? शामिल = '।

3. सहिष्णु पाठक: ग्राहक अज्ञात क्षेत्रों की अनदेखी करते हैं और सही ढंग से जीवित रहते हैं।

4. सिमेंटिक वर्शनिंग: 'मेजर। माइनर। कलाकृतियों, एसडीके और घटनाओं के लिए PATCH '।

5. स्वचालित: स्कीमा-डिफ़, लिंटर्स और सीडीसी परीक्षण ब्लॉक ब्रेकिंग परिवर्तन।

संस्करण कहां संग्रहीत करें (यांत्रिकी को संबोधित कर

REST/HTTP

URI संस्करण: '/v1/ऑर्डर '- मार्ग के लिए आसान, प्रवेश द्वार में सुविधाजनक। माइनस - विचारों के विकास को "अस्पष्ट" करता है।

मीडिया/शीर्षिका: 'स्वीकारें: अनुप्रयोग/vnd. उदाहरण। आदेश। v1 + json '- सटीक प्रारूप नियंत्रण; debunk करने के लिए कठिन।

क्वैरी संस्करण: '? api-version = 1 '- A/B के लिए सुविधाजनक है, लेकिन कैश/लॉग में खोना आसान है।

सिफारिश: प्रमुख लाइनों + सुविधा/क्षमता झंडे और मामूली एक्सटेंशन के लिए सामग्री नकारात्मक के लिए यूआरआई।

gRPC/Protobuf

पैकेज/सेवाएं: 'पैकेज भुगतान। v1; सेवा PaymentsV1; '- स्पष्ट लाइनें।

टैग नंबरिंग अपरिवर्तित है; हटाए गए टैग पुन: उपयोग नहीं किए जा सकते.

नए क्षेत्र - 'वैकल्पिक'; → नया '.v2' तोड़ ना।

ग्राफ़क्यूएल

URL में स्पष्ट बड़ी कंपनियों के बिना स्कीमा। @ deprecated और माइग्रेशन विंडो के माध्यम से एवोल्यूशन; "वास्तविक" प्रमुख एक नई समापन बिंदु योजना है।

नियंत्रण जटिलता/गहराई संविदा का हिस्सा है।

घटना-चालित (काफ्का/एनएटीएस/पल्सर)

घटना का नाम: 'भुगतान। अधिकृत। v1 'प्रकार में संस्करण है।

स्कीमा रजिस्ट्री (एवरो/जेसन स्कीमा/प्रोटोबुफ) संगतता मोड (बैकवर्ड/फॉरवर्ड/फुल) के साथ।

संक्रमण काल के लिए प्रमुख → डुअल-एमिट 'v1' और 'v2'।

संशोधन मॉडल और परिवर्तन नीति

सिमेंटिक वर्शनिंग

मेजर - ब्रेकिंग परिवर्तन: हटाना/नाम बदलना, सदस्यता कुंजी बदलना, स्टेटस का विभिन्न अर्थ, सत्यापन को कसना।

MINTER - additive: नए वैकल्पिक क्षेत्र/समापन बिंदु/घटनाएँ, सहिष्णु-पाठक के साथ नए एनम मूल्य।

PATCH - अनुबंध और शब्दार्थ को बदले बिना फिक्स करता है।

मूल्यह्रास और सूर्यास्त

मार्क अप्रचलित ('पदावनत: सही', '@ deprecated'), सूर्यास्त तिथि, वैकल्पिक और माइग्रेशन गाइड प्रकाशित करें।

HTTP - हेडर 'सनसेट', 'डिप्रेशन' में; घटनाओं में - एक अलग '.depressation। नोटिस '।

टेलीमेट्री का उपयोग यह तय करने के लिए कि क्या हटाना है।

शैली द्वारा रणनीतियाँ बनाना

REST

/ v1 ,/v2 पर प्रमुख लाइनें।

माइनर: स्कीमा एक्सटेंशन, '? क्षेत्र = ','? शामिल = '; सुरक्षित enum एक्सटेंशन।

नॉन-ब्रेकेज स्थिरता के लिए ETag/If-Match और idempotent POST।

त्रुटियाँ - स्थिर प्रारूप ('प्रकार', 'कोड', 'ट्रेस _ आईडी')।

gRPC

तोड़ ने के लिए नई सेवाओं/तरीकों का परिचय दें: ' V2। कैप्चर '।

त्रुटि स्थिति और समय सीमा शब्दार्थ अनुबंध का हिस्सा हैं; → नई विधि/सेवा बदलें।

स्ट्रीमिंग: संदेश आदेश पर सहमत हों और इसे नाबालिग में न बदलें।

ग्राफ़क्यूएल

खेतों और प्रकारों को स्वतंत्र रूप से जोड़ें; विलोपन - '@ deprecated' + माइग्रेशन विंडो के माध्यम से; बड़ी रीडिज़ाइन → नई योजना ('/graphql-v2 ')।

आत्मनिरीक्षण और विवरण - ग्राहक प्रवास के लिए होना चाहिए।

घटनाएँ

कोर बनाम समृद्ध: कोर स्थिर है, पास में रहते हैं और अलग-अलग होते हैं।

विभाजन कुंजी प्रमुख लाइन के भीतर अपरिवर्तित है।

प्रमुख प्रवासन - 'डुअल-एमिट' + प्रक्षेपण/उपभोक्ता प्रवास।

बातचीत और क्षमता झंडे

क्षमताएं: ग्राहक 'X-क्षमताओं को भेजता है: risk_score,price_v2'; सर्वर एक विस्तारित दृश्य के साथ जवाब देता है।

आंशिक प्रतिक्रियाओं के लिए वरीयता (HTTP) और संकेत।

सॉकेट/स्ट्रीम में - समर्थित एक्सटेंशन की सूची के साथ एक हैंडशेक संदेश।

दर्द के बिना प्रमुख संस्करणों का विमोचन

1. RFC/ADR: क्यों प्रमुख की आवश्यकता है, क्या टूटता है, जोखिम मैट्रिक्स।

2. दोहरी दौड़: 'v1' और 'v2' का समानांतर लॉन्च (डबल इवेंट पब्लिशिंग, दो गेटवे रूट, ट्रैफिक मिररिंग)।

3. प्रवासन अनुकूलक: भारी ग्राहकों के लिए 'v1↔v2' प्रॉक्सी/अनुवादक।

4. कैनरी: गेटवे में ग्राहक समूह/विषय/टैग द्वारा।

5. सूर्यास्त योजना: तिथियां, संचार, स्टैंड, परीक्षण डेटा, उपयोग निगरानी।

प्लेटफ़ॉर्म और बुनियादी

एपीआई गेटवे/सर्विस मेष: संस्करण, हेडर, पथ द्वारा रूटिंग; दर-सीमा и auth प्रति-संस्करण।

स्कीमा रजिस्ट्री और कैटलॉग: डिफ्यूज़इतिहास के साथ स्पेक्स/योजनाओं के लिए सत्य का स्रोत।

सीआई/सीडी: линтеры (स्पेक्ट्रल, बफ), स्कीमा-डिफ़ (ओपनएपीआई-डिफ़, बफ़ब्रेकिंग), सीडीसी (संधि)।

अवलोकन: संस्करण को लॉग/ट्रेल्स/मेट्रिक्स में शामिल किया जाना चाहिए।

संस्करण परीक्षण

पीआर में स्कीमा-डिफ़: ब्लॉक ब्रेकिंग।

उपभोक्ता-चालित अनुबंध: प्रदाता को वास्तविक उपभोक्ता अनुबंधों के खिलाफ परीक्षण किया जाता है

गोल्डन नमूने: संस्करणों के संदर्भ प्रतिक्रियाएं।

E2E कैनरी: संस्करणों के बीच p95/p99, त्रुटियों और समय की तुलना।

घटनाओं के लिए रीप्ले: अनुमानों को v2 पर फिर से इकट्ठा किया जाता है जिसमें कोई विसंगति नहीं होती है।

डाटा और डाटाबेस माइग्रेशन

REST/gRPC के लिए: डेटाबेस माइग्रेशन को एक्सटेंशन-एंड-कॉन्ट्रैक्ट के माध्यम से समन्वित किया जाता है (एक कॉलम जोड़ें पढ़ ना शुरू करें पुराने को हटाएं)।

घटनाओं के लिए: दोहरे उत्सर्जन और उपभोक्ता प्रवास; कभी-कभी - नए अनुमानों पर लॉग को फिर से दोहराना।

"बड़ेविस्फोट" न करें - रोलबैक के साथ चरणों में विभाजित करें।

सुरक्षा संबंध

स्कोप प्रति संस्करण: v1/v2 के लिए व्यक्तिगत OIDC-स्कोप/भूमिकाएँ।

टोकन के रहस्य/दावे संविदा का हिस्सा हैं; उनका परिवर्तन = प्रमुख।

पीआईआई/पीसीआई - अनावश्यक रूप से पेलोड का विस्तार न करें; नए क्षेत्र - न्यूनतम विशेषाधिकार के साथ।

एंटीपैटर्न

स्वैगर-वॉश: विनिर्देश अद्यतन, सर्वर नहीं (या इसके विपरीत)।

प्रोटोबुफ टैग का पुन: उपयोग डेटा का एक शांत भ्रष्टाचार है।

प्रमुख के बिना एनम अर्थ बदलना।

सौंदर्य प्रसाधन के लिए वैश्विक '/v2 '": टूटने के तथ्य के बिना एक संस्करण।

सूर्यास्त/प्रयोग मेट्रिक्स भूल गए: पुराने संस्करण को सुरक्षित रूप से हटाना असंभव है।

विभिन्न बड़ी कंपनियों के लिए एक सामान्य विषय: आदेशों और चाबियों का मिश्रण।

प्री-रिलीज़चेकलिस्ट

• परिवर्तन योजक हैं या एक अलग प्रमुख लाइन तैयार की गई है।
• लिंटर्स और स्कीमा-डिफ हरे रंग के होते हैं (ब्रेकिंग क्रॉल नहीं होता है)।
• अद्यतन SDK/उदाहरण/प्रलेखन, संगतता फुटनोट।
• ग्राहकों पर सहिष्णु पाठक सक्षम; enum-fallback परीक्षण किया
• प्रमुख के लिए - दोहरी योजना, एडेप्टर, कैनरी, सूर्यास्त की तारीखें और मेलिंग।
• मेट्रिक्स/लॉग/ट्रेल्स में एक संस्करण और इसके द्वारा विभाजन होता है।
• तुलना करने के लिए एक स्टैंड और सुनहरा सेट है।
• घटनाओं के लिए, स्कीमा रजिस्ट्री बैकवर्ड/फुल मोड में है, विभाजन कुंजी अपरिवर्तित हैं।

नमूना टेम्पलेट्स

REST (URI + बातचीत)

रूट: '/api/v2/ऑर्डर/{ id} '

Заголовок: 'प्राथमिकता: शामिल = आइटम, ग्राहक', 'एक्स-क्षमताएं: risk_score'

मूल्यह्रास: 'सूर्यास्त: 2026-06-30', 'लिंक: ; rel = "वैकल्पिक" '

प्रोटोबुफ/जीआरपीसी

proto package payments. v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

घटनाएँ

'भुगतान। कब्जा कर लिया। v2 '(कोर) और' भुगतान। समृद्ध। v2 '(विवरण)।

संक्रमण अवधि के लिए, निर्माता 'v1' and 'v2' जाता है।

FAQ

वास्तव में '/v2 'की आवश्यकता कब है?

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

क्या आप REST में एक स्पष्ट संस्करण के बिना रह सकते हैं?

केवल छोटी प्रणालियों के लिए। बाहरी एकीकरण के लिए, स्पष्ट प्रमुख लाइनें बेहतर हैं।

पुराने संस्करण को कब तक रखना है?

पारिस्थितिकी तंत्र पर निर्भर करता है। बाहरी भागीदारों के लिए, आमतौर पर शुरुआती अधिसूचना और कैनरी के साथ 6-12 महीने।

एपीआई से अलग घटना संस्करण कैसे है?

घटनाएँ - केवल जोड़ें; नए शब्दार्थ = नए प्रकार '.v2' और दोहरे-उत्सर्जन। विभाजन कुंजी संविदा का हिस्सा है।

कुल

वर्शनिंग रणनीतियां प्रक्रिया और उपकरण हैं: डिफ़ॉल्ट योजक विकास, स्पष्ट प्रमुख रेखाएं, क्षमता-वार्ता, दोहरे-रन और सूर्यास्त। स्वचालित संगतता जांच, उपयोग टेलीमेट्री और प्रलेखन अनुशासन जोड़ें - और आपके एपीआई "रात के प्रवास" और ग्राहकों में अप्रत्याशित बूंदों के बिना जल्दी से विकसित होंगे।