एपीआई संगतता और अद्यतन

1) संगतता बुनियादी बातें

एडिटिव-फर्स्ट: पुराने को तोड़े बिना नया जोड़ें (नए वैकल्पिक क्षेत्र/समापन बिंदु, नए एनम मान)।

स्थिर अनुबंध: "विनिर्देश कार्यों में क्या वादा किया गया है;" व्यवहार प्रलेखि

पिछड़ा> आगे: पिछड़े संगतता प्राथमिकता; सहिष्णु-पाठकों के माध्यम से आगे की अनुमति है।

दस्तावेज़ प्राथमिक हैं: सत्य का एकमात्र स्रोत योजना का रजिस्ट्री संस्करण है (OpenAPI/AsyncAPI/Proto)।

स्पष्ट विकास: तोड़ ना - केवल एक नए प्रमुख संस्करण और एक प्रवासन गाइड के माध्यम से।

2) परिवर्तनों का वर्गीकरण

2. 1 संगत (MINTER/PATCH)

वैकल्पिक फ़ील्ड/हेडर, नए एंडपॉइंट, डिफ़ॉल्ट के साथ क्वेरी पैरामीटर जोड़ें।

बढ़ ती सीमा ('पृष्ठ _ आकार', टीटीएल), कोड/शब्दार्थ बदले बिना त्रुटियों को स्पष्ट करना।

यदि ग्राहक "अज्ञात" (सहिष्णु-पाठक) को अनदेखा करते हैं तो एनम मान जोड़ें।

2. 2 अस्पष्ट (व्यवहार)

डिफ़ॉल्ट बदलना, छंटाई क्रम, पतली समयसीमा, कोटा - व्यापार तर्क को "तोड़" सकता है। RFC + घोषणा और कैनरी की आवश्यकता है।

2. 3 ब्रेकिंग (मेजर)

फ़ील्ड का नाम बदलें/हटाएँ, प्रकार/प्रारूप बदलें, त्रुटि कोड बदलें, संविदाओं/सत्यापन योजनाओं की असंगति को उलटें।

3) वर्शनिंग पॉलिसी

रणनीति: 'पथ संस्करण' ('/v1 ', '/v2')।

माइनर/पैच: "जोड़ें, टूटें नहीं।"

डेटेड हेडर (वैकल्पिक): नरम वृद्धिशील परिवर्तनों के लिए 'X-API-Version-Date'।

मीडिया प्रकार (Op।): 'स्वीकार करें: आवेदन/vnd। acme। ठीक दानेदार के लिए v1 + json '।

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

4. 1 संचार शीर्षक

Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4. 2 निकासी आदेश

1. पोर्टल/मेलिंग सूची/एसडीके रिलीज नोट्स में घोषणा।

2. चेतावनी खिड़की ≥ 90-180 दिन।

3. गोद लेने के डैशबोर्ड में स्टेटस।

4. सूर्यास्त के बाद - 410 गॉन या अनुग्रह अवधि के लिए "रीड-ओनली" मोड, अगर सहमत हो।

5) संस्करणों के प्रवासन और सह-अस्तित्व

रिपोर्टों के साथ संक्रमण और सामंजस्य में दोहरे-लेखन/दोहरे-पढ़े।

एडेप्टर्स (अस्थायी): पुराने पेलोड के गेटवे रूपांतरण → नई योजनाएं; एडाप्टर जीवनकाल सीमित है।

एसडीके मदद: रिलीज़ करता है जो दोनों संस्करणों का समर्थन करता है, डेक्रिमेंट चेतावनी (प्रति प्रक्रिया 1 समय) के साथ।

फ़ीचर फ़्लैग: कुंजियों/किरायेदारों की सूची के अनुसार नए शब्दार्थों को शामिल करना।

6) पिछड़ा और आगे की संगतता

6. 1 पिछड़ा (पुराने क्लाइंट - नया सर्वर)

प्रकार प्रारूप/अनिवार्य नहीं बदलें।

नए क्षेत्र केवल वैकल्पिक हैं।

त्रुटियाँ - पुराना 'error _ code', नया कोड जोड़ें, बदलें नहीं.

6. 2 फॉरवर्ड (नए क्लाइंट - पुराने सर्वर)

'विकल्प '/'/संस्करण' के माध्यम से क्षमताओं के लिए जाँचें।

अनुग्रह व्यवहार: ग्राहक को लापता सुविधाओं के प्रति सहिष्णु होना चाहिए।

7) अनुबंध और स्वचालित जांच

रजिस्ट्री: स्टोर स्कीमा संस्करण; पीआर → ब्रेकिंग/नॉन-ब्रेकिंग रिपोर्ट खोदता है

लिंटर: नाम/प्रकार, पहचान, पृष्ठभूमि, स्थिर कोड।

सीडीसी (उपभोक्ता-संचालित अनुबंध): आपूर्तिकर्ता के सीआई (संधि और एनालॉग) में इंटीग्रेटर परीक्षण।

गेट: PR 'major bump '/RFC के बिना टूटने पर अवरुद्ध हो जाता है।

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8) कैनरी विस्तार और रिवर्स

कैनरी: 10% → 25% → 50% → 100% यातायात; एसएलओ गिरावट पर ऑटो-रोलबैक (5xx/विलंबता/429)।

बीटा कुंजी: मिश्रधातु द्वारा नए संस्करणों तक पहुंच।

रिलीज फ्रीज: दहन के दौरान त्रुटि-बजट।

स्वीकृति विश्लेषण: नए संस्करण, प्रवासन समय पर यातायात/ग्राहकों का हिस्सा।

9) विस्तार से संगतता: त्रुटियां, पृष्ठभूमि, निष्क्रियता

9. 1 त्रुटियाँ

मौजूदा स्क्रिप्ट में HTTP स्थिति नहीं बदलें।

'error _ code' - स्थिर; नए कोड केवल जोड़ें।

'एप्लीकेशन/प्रॉब्लम + json' एक एकल प्रारूप है।

9. 2 पृष्ठभूमि

यदि पुराना 'ऑफसेट/लिमिट' समर्थित है तो कर्सर/कीसेट = MINTER पर स्विच करें।

सॉर्ट '(updated_at,id)' और कर्सर स्थिरता का दस्तावेज़.

9. 3 पहचान

लिखने के लिए - 'Idempotency-Key' + '409 - संघर्ष के मामले में।

प्रवासन को पहचान के शब्दार्थ को नहीं बदलना चाहिए।

10) गेटवे परिवर्तन (जब उपयुक्त हो)

नक्शा v1→v2 फ़ील्ड, त्रुटियों को सामान्य बनाएं, तिथि/धन प्रारूप परिवर्तित करें।

रेल: परिवर्तन पारदर्शी और लॉगेबल हैं; टूटने को न छिपाएं, लेकिन समय-सीमित पुल के रूप में उपयोग करें।

11) संचार और पोर्टल

Changelog с датами ('जोड़ा/परिवर्तित/पदावनत/हटाया/नियत')।

संस्करण कार्ड: स्थिति (बीटा/जीए/पदावनत), सूर्यास्त तिथि, गाइड के लिंक।

अधिसूचना वेबहूक: 'मूल्यह्रास। नोटिस ',' संस्करण। जारी ',' योजना। परिवर्तन '।

एसडीके रिलीज़ नोट्स + पोर्टल बैनर।

12) सफलता मेट्रिक्स

दत्तक दर v2 (अनुरोध/ग्राहक के अनुसार)।

पिछड़े की तुलना की घटनाएं।

रिलीज से पहले/बाद में त्रुटि मिश्रण (4xx/5xx/429 शेयर)।

टाइम-टू-एडॉप्ट मंझला।

समर्थन भार (टिकट/सप्ताह)।

कॉस्ट-टू-सर्व।

13) साँचा और उदाहरण

13. 1 संस्करण शीर्षक और कमी

X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13. 2 संस्करण नीति (YAML टुकड़ा)

yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]

13. 3 ओपनएपीआई फील्ड एपेंड संगत

yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive

14) रिलीज़ चेकलिस्ट (माइनर/मेजर)

माइनर

• DIFF: नॉन-ब्रेकिंग, लिंटर ग्रीन
• प्रलेखन/एसडीके अद्यतन (उदाहरण/कोडेक)
• कैनरी + ऑटो-एसएलओ रोलबैक
• कॉम प्लान, पोर्टल पेज
• गोद लेना और त्रुटि डैशबोर्ड

मेजर

• RFC/ADR, सूर्यास्त तिथि और ≥90 विंडो -180 दिन
• पुल और माइग्रेशन गाइड
• दोहरी लिखने/पढ़ने और सामंजस्य
• दोनों एपीआई + अलर्ट के साथ एसडीके
• प्रमुख इंटीग्रेटर के साथ पाय

15) कार्यान्वयन योजना (3 पुनरावृत्ति)

1. फाउंडेशन (2 सप्ताह):

सीआई में योजनाओं, लिंट और ऑटो-डिफ की रजिस्ट्री; संगतता नीति; 'Deprecation/Sunset' शीर्षक।

2. प्रबंधित रिलीज़ (3-4 सप्ताह):

कैनरी, फ्लैग, एसएलओ अलर्ट; संस्करण पोर्टल; एसडीके 2 शाखाओं के लिए समर्थन के साथ जारी करता है।

3. स्वचालन और स्केल (सतत):

सीआई में उपभोक्ताओं के सीडीसी परीक्षण, गोद लेने के रुझानों, स्वचालित सूचनाओं और अनुस्मारक पर सूर्यास्त पूर्वानुमान।

16) मिनी-एफएक्यू

क्या मैं एक प्रमुख के बिना क्षेत्र प्रकार बदल सकता हूं?

नहीं, यह नहीं है। यहां तक कि "stroka→chislo" भी टूट रहा है। नया क्षेत्र भरें, पुराना पदावनत है।

Enum: क्या आप मान जोड़ सकते हैं?

हां, अगर ग्राहक सहिष्णु-पाठक हैं। अन्यथा - पहले एक अलर्ट और बीटा।

पुराने संस्करण को रखने के लिए कितना?

अब तक, नए ≥95% को अपनाने को बनाए रखा गया है। नीति में समय सीमा तय करें।

कुल

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