एपीआई अनुबंध संगतता

अनुबंध संगतता क्यों

अनुबंध संगतता मौजूदा एकीकरण को तोड़े बिना एपीआई को विकसित करने की क्षमता है। बढ़ ती प्रणालियों में, एपीआई क्लाइंट कोड की तुलना में अधिक बार बदलते हैं; संगतता आपको "बड़ीचाल" की व्यवस्था किए बिना, सुविधाओं को पुनरावृत्ति से मुक्त करने की अनु

मुख्य विचार: अनुबंध प्राथमिक है, परिवर्तन संगतता नियमों के अनुसार किए जाते हैं और स्वचालित रूप से जांचे जाते हैं।

बुनियादी अवधारणाएँ

संविदा - औपचारिक इंटरफेस विनिर्देश: संसाधन/विधियां/घटनाएं, डेटा स्कीमा, त्रुटि कोड, सीमाएं, एसएलए, सुरक्षा आवश्यकताएं।

प्रदाता - एपीआई का मालिक। उपभोक्ता - ग्राहक/एकीकरण।

• पिछड़ा: नया आपूर्तिकर्ता पुराने उपभोक्ताओं के साथ काम करता है
• फॉरवर्ड: पुराने आपूर्तिकर्ता नए उपभोक्ताओं के साथ काम करते हैं (आमतौर पर "सहिष्णु पाठकों" द्वारा प्राप्त
• पूर्ण: पिछड़े और आगे (सबसे मजबूत विकल्प) दोनों देखे जाते हैं।
• एडिटिविटी - मौजूदा तत्वों को तोड़े बिना वैकल्पिक तत्व जोड़ें।

Versioning नीति

• मेजर - ब्रेकिंग परिवर्तन (केवल तभी जब एक नई एपीआई लाइन जारी की जाती है: '/v2 ',' सेवा। v2 ')।
• MINTER - additive परिवर्तन (नए वैकल्पिक क्षेत्र/विधियाँ)।
• PATCH - अनुबंध को बदले बिना फिक्स करता है।
• अस्वीकृति नीति: अप्रचलित तत्वों की घोषणा, समर्थन विंडो (सूर्यास्त), हेडर/मेटाडेटा में चेतावनी, वापसी योजना।

सुरक्षित बनाम खतरनाक परिवर्तन

सुरक्षित (आमतौर पर पीछे-संगत)

JSON/Protobuf/Avro में एक वैकल्पिक क्षेत्र जोड़ें।

नया समापन बिंदु/विधि/घटना जोड़ें।

यदि उपभोक्ता अज्ञात मूल्यों के प्रति सहिष्णु हैं तो नए मूल्यों के साथ विस्ता

सीमा बढ़ाना (उदाहरण के लिए, 'अधिकतम') न्यूनतम कसने के बिना।

सही मूलभूत के साथ शून्य जोड़ ना।

वर्णन/उदाहरण पाठ संपादित करें।

खतरनाक (संगतता को तोड़ ता है)

फ़ील्ड का नाम बदलें/मिटाएँ, उनके प्रकार या अनिवार्य बदलें।

स्थिति कोड/त्रुटि शब्दार्थ परिवर्तन (उदाहरण के लिए, '200' था, '204' या '404' बन गया)।

पहचानकर्ताओं का प्रारूप बदलना (UUID → int)।

संस्करण के बिना सत्यापन (सख्त न्यूनतम/पैटर्न) को कसना।

जीआरपीसी धाराओं/घटनाओं में क्रम और संरचना को बदलना।

नए क्षेत्रों के लिए प्रोटोबुफ में टैग संख्या का पुनः उपयोग करें।

इंटरैक्शन स्टाइल द्वारा इंटरऑपरेबिलिटी

REST/HTTP + JSON स्कीमा

Additivity: हम नए क्षेत्रों को 'वैकल्पिक '/' शून्य' के रूप में चिह्नित करते हैं।

ग्राहक पर सहिष्णु पाठक: अज्ञात क्षेत्रों की अनदेखी करें; आदेश पर निर्भर नहीं।

वर्शनिंग: प्रमुख - रास्ते में ('/v2 ') या मीडिया प्रकार (' एप्लिकेशन/vnd)। उदाहरण। v2 + json ')।

ETag/If-Match: रेसिंग के बिना सुरक्षित अपडेट के लिए।

त्रुटि: एकल प्रारूप ('प्रकार', 'कोड', 'शीर्षक', 'विस्तार', 'ट्रेस _ आईडी'), एक प्रमुख के बिना 'कोड' का मान नहीं बदलते हैं।

Pagination: कर्सर ऑफसेट करने के लिए बेहतर हैं; 'अगला _ कर्सर' फ़ील्ड जोड़ें, मौजूदा का अर्थ न बदलें।

gRPC/Protobuf

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

नया क्षेत्र सर्वर पर उचित मूलभूत तयशुदा के साथ 'वैकल्पिक '/' दोहराया' है।

स्ट्रीमिंग-आरपीसी में क्रम और अनिवार्य संदेश को न बदलें।

त्रुटि स्थितियाँ स्थिर हैं ('INVALID _ CORGENGT', 'FELT _ PRECONDITION', आदि); नए शब्दार्थ - विधि/सेवा का एक नया संस्करण।

इवेंट-चालित (काफ्का/एनएटीएस/पल्सर) + एवरो/जेसन स्कीमा

नामकरण घटनाएँ: 'डोमेन। क्रिया। v {प्रमुख} '।

नए क्षेत्र वैकल्पिक हैं; कोर और संवर्धन ('.enriched') को अलग करें।

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

एनम एक्सटेंशन उपभोक्ता-पक्ष सहिष्णु पाठक के लिए मान्य है।

एग्रीगेट = ब्रेकिंग परिवर्तन के लिए पार्टीशन/ऑर्डर कुंजी परि

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

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

बिना प्रमुख के प्रकार/गैर-शून्य को न बदलें।

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

सतत विकास पैटर्न

Additive-first: बिना तोड़े विस्तार।

क्षमता वार्ता: ग्राहक रिपोर्ट करते हैं कि वे समर्थन (हेडर/मापदंड/समझौते), सर्वर समायोजित करता है।

अनुबंध की सीमाएँ: एमजीसी (न्यूनतम वारंटी अनुबंध) और अलग-अलग एक्सटेंशन (रिवर्स पिरामिड मॉडल)।

डिफ़ॉल्ट रूप से सहिष्णुता: क्लाइंट अनावश्यक अनदेखी करते हैं और अज्ञात एनम (फॉलबैक) मानों को सही ढंग से संभालते हैं।

डुअल-राइट/डुअल-एमिट: प्रमुख परिवर्तनों के लिए, कुछ समय के लिए समानांतर में 'v1' और 'v2' जारी करें।

सूर्यास्त शीर्षिका/घटनाएँ: संस्करण हटाए जाने पर अग्रिम में सूचित करें।

शासन और स्वचालन

• OpenAPI/स्पेक्ट्रल: नामकरण, पृष्ठभूमि, त्रुटि कोड, क्षेत्र प्रारूप।
• Buf/Protobuf: टैग के पुन: उपयोग को अस्वीकार करना, पैकेट संकेतन।
• AsyncAPI/स्कीमा रजिस्ट्री: सीआई-स्तर स्कीमा संगतता।
• अनुबंध कैटलॉग (SSOT): फैलाने वाले इतिहास के साथ केंद्रीकृत स्कीमा/संस्करण रजिस्टर।
• एपीआई गिल्ड: गिल्ड/कमेटी जो नियम, टेम्पलेट और समीक्षा परिवर्तन को अपनाती है।
• परिवर्तन प्रबंधन: RFC/ADR, रिलीज नोट्स, माइग्रेशन गाइड।

संगतता परीक्षण

सीआई में स्कीमा-डिफ़: ब्लॉक ब्रेकिंग केक (OpenAPI-diff, Buf ब्रेकिंग, SR संगतता)।

उपभोक्ता-संचालित अनुबंध (सीडीसी): संधि/समान - आपूर्तिकर्ता बनाम उपभोक्ता-विशिष्ट अनुबंध।

स्वर्ण नमूने: प्रतिगमन के लिए संदर्भ प्रश्न/प्रतिक्रियाएं और घटना

E2E कैनरी: ट्रैफिक/व्यक्तिगत घाघ समूहों के हिस्से के लिए रोलिंग।

अराजकता/विलंबता: टाइमआउट/रिट्रे चेक - एक विलंबता-एसएलओ परिवर्तन को एक अनुबंध परिवर्तन माना जाता है।

माइग्रेशन और पदावनत

1. पदावनत घोषित करें: आइटम चिह्नित करें, सूर्यास्त शब्द और विकल्प निर्दिष्ट करें।

2. संगतता अवधि बनाए रखें: दोहरे-लेखन/दोहरे-उत्सर्जन, पुल, एडेप्टर।

3. टेलीमेट्री इकट्ठा करें: पुराने का उपयोग और कौन करता है?

4. संचार: मेलिंग, रिलीज नोट्स, टेस्ट स्टैंड।

5. हटाना: विंडो समाप्त होने के बाद - एक निश्चित रिलीज के साथ हटाना।

परिवर्तनों के उदाहरण

REST

json
{ "id":"p1", "status":"authorized" }

json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }

अज्ञात क्षेत्रों की अनदेखी करने वाले ग्राहक नहीं टूटते

प्रोटोबुफ

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

घटना

'भुगतान। अधिकृत। v1 '(कोर) +' भुगतान। समृद्ध। v1 '(संवर्धन)। महत्वपूर्ण पथ उपभोक्ता कोर पढ़ ते हैं और संवर्धन पर निर्भर नहीं हैं।

एंटीपैटर्न

स्वैगर-वॉश: औपचारिक रूप से एक विनिर्देश है, लेकिन सेवा का व्यवहार इसके साथ है।

चुपके से तोड़ ना: नए संस्करण और माइग्रेशन विंडो के बिना परिवर्तित प्रकार/स्थिति/प्रारूप।

एक सार्वजनिक अनुबंध के रूप में रॉ सीडीसी घटनाएं: लीक डीबी योजनाएं, विकास की असंभव।

कठोर ग्राहक: अज्ञात क्षेत्रों/मूल्यों पर गिरता है; एक सहिष्णु पाठक की अनुपस्थिति।

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

"गैर-अनुबंध" के रूप में लेटेंसी: p95 अप्रत्याशित रूप से लंबा था - उपभोक्ता टाइमआउट में टूट जाते हैं।

संगतता चेकलिस्ट (विलय से पहले)

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

FAQ

पिछड़ा आगे की संगतता से कैसे भिन्न है?

पिछड़ा - नया सर्वर पुराने क्लाइंट को नहीं तोड़ ता है। फॉरवर्ड - नए क्लाइंट पुराने सर्वर (सहिष्णु पाठक और साफ चूक के माध्यम से) पर नहीं टूटते हैं।

आप '/v2 'कब करते हैं?

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

क्या आप स्कीमा रजिस्ट्री/लिंटर्स के बिना रह सकते हैं?

सैद्धांतिक रूप से - हाँ, व्यावहारिक रूप से - ये लगातार रीग्रेशन और "छिपे हुए" ब्रेकडाउन हैं। स्वचालन बंद भुगतान करता है।

Enum बढ़ाया जा सकता है?

हां, अगर क्लाइंट सही ढंग से अज्ञात मानों को हैंडल करते हैं (फॉलबैक/अनदेखा)। अन्यथा - प्रमुख।

कुल

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