एपीआई वर्शनिंग और अनुबंध संगतता
टीएल; डीआर
संगतता अनुशासन है, भाग्य नहीं। एक स्पष्ट संस्करण नीति (SemVer) रखें, गणित को बदलें (क्या "टूटता है", क्या नहीं), अनुबंध परीक्षण, स्कीमा रजिस्टर और सनसेट प्रक्रियाएं। पैसे और अनुपालन के लिए - UI एकत्रीकरण के लिए vN के साथ सख्त REST/gRPC - '@ deprecated' के साथ विकासवादी GraphQL। हमेशा: कैनरी ट्रैफ़िक, बैकवर्ड अनुकूलता - एक रिलीज़ चक्र, माइग्रेशन गाइड, फ़ील्ड टेलीमेट्री।
1) बुनियादी अवधारणाएं और लक्ष्य
बैकवर्ड-संगत (बीसी): पुराने क्लाइंट नए सर्वर के लिए उपयुक्त हैं.
फॉरवर्ड-संगत (एफसी): नए क्लाइंट पुराने सर्वर (सीमित) के लिए उपयुक्त हैं।
वायर संगतता: "वायर" पर प्रारूप टूटता नहीं है (विशेष रूप से gRPC/Protobuf के लिए महत्वपूर्ण)।
SemVer: 'मेजर। माइनर। PATCH '- अनुबंध को तोड़ दें → मेजर को बढ़ाएं।
लक्ष्य विघटनकारी परिवर्तनों को कम करना और पूर्वानुमानित प्रवासन खिड़कियां प्रदान करना है।
2) मैट्रिक्स बदलें: आप क्या कर सकते हैं और क्या नहीं कर सकते
3) विभिन्न एपीआई शैलियों के लिए नीतियां
3. 1 REST
यूआरआई में संस्करण ('/v1/... ') या डोमेन (' api-v1। '). शीर्षिका संस्करण - केवल आंतरिक मामलों के लिए।
जोड़ें, हटाएं नहीं: नए क्षेत्र - ठीक है, पुराने - चिह्न आरेख में 'पदावनत' के रूप में और कम से कम एक चक्र के लिए छोड़ दें।
स्टेटस/त्रुटियां: कोड और संरचना को न बदलें। कोड/त्रुटि। संदेश/त्रुटि। विवरण '।
Idempotency अपरिवर्तित है: 'Idempotency-Key' के साथ एक सुरक्षित 'POST' को 'व्यवहारिक रूप से अलग' चुनौती में न बदलें।
3. 2 जीआरपीसी/प्रोटोबुफ
फ़ील्ड संख्याएँ पवित्र हैं: हटाए गए संख्याओं का पुन: उपयोग न करें, 'आरक्षित' के रूप में चिह्नित करें।
केवल नए वैकल्पिक/रिपिट फ़ील्ड जोड़ ना; "कठिन अनिवार्य" - सत्यापन के माध्यम से, 'पूछताछ' नहीं।
संस्करण पैकेज: 'भुगतान। v1 ',' भुगतान। v2 '।
सेवा संगतता: नई आरपीसी - एक नई विधि; हम पुराने के व्यवहार को नहीं बदलते हैं।
proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}3. 3 ग्राफ़क्यूएल
v2 के बिना विकास: फ़ील्ड/प्रकार जोड़ें; विलोपन - खिड़की की घोषणा के साथ '@ deprecated (कारण)' के माध्यम से।
पर्याप्त प्रश्न: सार्वजनिक ग्राहकों के लिए, प्रश्नों के एक सफेदी का उपयोग करें - संगतता को नियंत्रित करना आसान है।
फील्ड-लेवल authZ और टेलीमेट्री: जानें कि कौन से क्षेत्र वास्तव में हटाने से पहले उपयोग किए जाते हैं।
graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}3. 4 वेबहूक
पथ में संस्करण ('/वेबहुक/v1/भुगतान ') और निश्चित घटना लिफाफा (' घटना _ आईडी ',' प्रकार ',' टीएस ',' डेटा ')।
हस्ताक्षर/NMAS अपरिवर्तित रखें; नए एल्गोरिदम - एक ध्वज के साथ एक विकल्प के रूप में।
एक्सटेंशन - केवल नए फ़ील्ड्स डेटा के माध्यम से। 'और' हेडर '- पुराने लोगों को हटाए बिना।
4) गेटवे एपीआई और संस्करण मार्ग
नियम-आधारित रूटिंग: डोमेन द्वारा हेडर 'एक्स-एपी-संस्करण' द्वारा उपसर्ग '/v1 'द्वारा।
छाया/कैनरी: नए संस्करण पर कुछ उत्पादन यातायात को "छाया में" दर्शाते हैं, जवाब की तुलना करें।
दर/कोटा प्रति-संस्करण: प्रवास के दौरान पुराने ग्राहकों की रक्षा करता है।
REST के लिए सूर्यास्त शीर्षिका:- 'सूर्यास्त:
' - संस्करण शटडाउन तिथि - 'अवसादन: सही' - संस्करण अप्रचलित हो जाता है
- 'लिंक:
; rel = "deprecation" '- चेंजलॉग/माइग्रेशन गाइड पर
nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}5) योजना रजिस्टर और अनुबंध
OpenAPI/JSON स्कीमा для REST; प्रोटोबुफ विवरणकर्ता для gRPC; एसडीएल रजिस्ट्री для ग्राफक्यूएल।
सीआई जांच: पीआर में लिंटर + "ब्रेकिंग-चेंज चेक"।
उपभोक्ता-संचालित अनुबंध (सीडीसी): उपभोक्ता परीक्षण (संधि/एनालॉग) - असंगत ब्रेक के खिलाफ सुरक्षा।
Changelog: मशीन-पढ़ने योग्य (उदाहरण के लिए, 'CHANGELOG। रजिस्ट्री में md '+ रिलीज नोट्स)।
6) क्षेत्रों का विकास: अंगूठे के नियम
ID/keys: नए फ़ील्ड '_ v2' और संक्रमण अवधि के बिना प्रारूप (UUID↔int) को नहीं बदलें।
समय/मुद्रा: UTC ISO-8601/epoch और amount_minor + मुद्रा रखें; पैमाने (पेनी/सेंट) नहीं।
Enum: मूल्य जोड़ें - ठीक है; पुराने लोगों का अर्थ न बदलें। REST के लिए, स्ट्रिंग मान दें, इंट्स नहीं।
Pagination: कर्सर-आधारित अधिक स्थिर; कर्सर के शब्दार्थ को न बदलें।
7) कमी और "सूर्यास्त" प्रक्रिया
1. घोषणा (T-90/60): चेंजलॉग, पार्टनर्स को मेल, 'डिप्रेशन/सनसेट' सुर्खियों में।
2. डुप्लिकेट अवधि: V1 और V2 समानांतर में काम करते हैं; V1 प्रतिक्रियाओं/लॉग में चेतावनी से सुसज्जित है।
3. उपयोग टेलीमेट्री: और कौन V1 कहता है? बिंदु संपर्क।
4. जमना V1: सिर्फ बग सुधार/कोई सुविधा नहीं.
5. Sunset-410 चला गया या माइग्रेशन अनुदेश ब्लॉक पृष्ठ।
8) दर्द-मुक्त रिलीज: रणनीति बनाना
ब्लू/ग्रीन या वेटेड रूटिंग: 1-5-25-50-100% ट्रैफिक।
संगतता खिड़की: कम से कम 1-2 मामूली रिलीज, बाहरी एपीआई के लिए अधिक बार 6-12 महीने।
बिना उन्नयन के नए तर्क क्षेत्र/शाखाओं को शामिल करने के लिए फ्लैग की सुविधा।
पढ़ें/लिखें-विभाजन: पहले नया क्षेत्र पढ़ ने के लिए समर्थन जोड़ें, फिर इसे लिखना शुरू करें
9) अंतर परीक्षण (अभ्यास सूट)
पुराने संस्करणों से प्रतिक्रियाओं के लिए गोल्डन परीक
सर्किट के डिफ परीक्षण: सीआई में कोई ब्रेकिंग नहीं।
V2 (छाया) के लिए मंचन पर रीप्ले उत्पादन चलता है।
बैक/फॉरवर्ड स्क्रिप्ट: पुराने सर्वर पर नया क्लाइंट और इसके विपरीत (जहां एफसी मान्य है)।
वेबहूक के अनुबंध परीक्षण: हस्ताक्षर, प्रारूप, समय का सत्यापन।
10) संस्करण प्रक्रिया के मेट्रिक्स और एसएलओ
अंतिम MINTER पर ग्राहकों का% (सूर्यास्त से पहले ≥ 80% का लक्ष्य)।
प्रति रिलीज संगतता/अनुपलब्धता त्रुटियाँ (लक्ष्य 0)।
विरासत कॉल का हिस्सा (सूर्यास्त तक कम)।
क्लाइंट माइग्रेशन टाइम (औसत/p95)।
संस्करणों के बीच विलंबता/प्रतिगमन डेल्टा (मूल से भी बदतर नहीं)।
11) कलाकृतियों के उदाहरण
OpenAPI (खंड, क्षेत्र अवक्षेपण):yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }graphql type Query { payout(id: ID!): Payout }12) आसन्न चैनलों की संस्कृति
SDK/CLI: SemVer + API संस्करण निर्भरता, README में संगतता निर्धारित।
घटनाओं/धाराओं (WS/Kafka): 'envelope में संस्करण। संस्करण '; नई विशेषताएं - वैकल्पिक; dedup और फिर से शुरू संस्करणों के बीच समान काम करते हैं।
रिपोर्टिंग/सीएसवी: फ़ाइल नाम/शीर्षिका में संस्करण; दाएँ में स्तम्भ जोड़ें क्रम/प्रकार नहीं बदलें।
13) शासन और भूमिकाएँ
अनुबंध मालिक (डोमेन मालिक), स्टीवर्ड एपीआई (नियम और लिंटर्स), रिलीज प्रबंधक (सूर्यास्त/संचार)।
परिवर्तनों को तोड़ ने के लिए RFC प्रक्रिया: व्यावसायिक औचित्य, प्रवासन योजना, कलाकृतियां, तारीखें
एकीकृत एपीआई निर्देशिका: जहाँ आरेख, संस्करण, सूर्यास्त पंचांग, संपर्क दृश्यमान हैं.
14) एंटी-पैटर्न
"शांत" ब्रेक: एक संस्करण के बिना स्थिति/त्रुटि/फ़ील्ड प्रकार बदलें।
प्रोटोबुफ संख्याओं का पुन: उपयोग - रिप्ले और पुराने ग्राहकों को नष्ट करता है।
फ़ील्ड टेलीमेट्री के बिना ग्राफ़क्यूएल - स्पर्श हटाना।
बिंदु विकास के बजाय वैश्विक v2 कुल - मेगामाइग्रेशन।
सार्वजनिक एपीआई के लिए क्वेरी पैरामीटर में संस्करण एक गैर-स्पष्ट और कमजोर योजना है।
कोई प्रवासन गाइड और उदाहरण नहीं हैं - भागीदार स्टाल, समय सीमा बाधित होती है।
15) नए संस्करण की चेक-सूची जारी
- अपडेटेड स्कीमा (OpenAPI/Protobuf/SDL), लिंटर और ब्रेकिंग-चेक पास हुए।
- एकीकरण और अनुबंध परीक्षण (सीडीसी) जोड़ा गया।
- SDK/नमूना कोड/माइग्रेशन गाइड और Changelog तैयार।
- Deprecation/Sunset सक्षम (पुराना संस्करण) + पृष्ठ को कैसे पलायन करें।
- कैनरी/छाया योजना, अलर्ट और डैशबोर्ड मेट्रिक्स की तुलना करते हैं।
- एक सहमत अवधि के लिए पिछड़े संगतता बनाए रखा जाता है।
- रोलबैक योजना और जोखिम मैट्रिक्स सहमत हुए।
सारांश
एक स्थिर एपीआई एक प्रक्रिया है, न कि "एक बार और सभी के लिए। "नियमों द्वारा लाइव: SemVer + ad-ovolution + सर्किट रजिस्टर + अनुबंध परीक्षण + सनसेट प्रक्रियाएं। अलग शैलियाँ (REST/gRPC/GraphQL) और उनकी नीतियां, गेटवे एपीआई के लिए मार्ग संस्करण, कैनरी को रोल आउट करें, प्रभाव को मापें। इस तरह आप "आश्चर्य तोड़ ने" से बचेंगे, साझेदार एकीकरण में तेजी लाएंगे और मौद्रिक और अनुपालन-महत्वपूर्ण डोमेन के लिए पूर्वानुमेयता बनाए रखेंगे।