प्रौद्योगिकी और बुनियादी ढांचा - एपीआई Versioning

एपीआई वर्शनिंग

1) आपको इसकी आवश्यकता क्यों है

• रिलीज के दौरान घटनाओं के जोखिम को कम करता है,
• आपको सुधार और सुरक्षा निर्धारित करने की अ
• व्यवसायों को साझेदार पलायन के लिए पूर्वानुमानित समय सीमा देता है।

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

PATCH (नहीं तोड़ ना): अनुबंध को बदले बिना सुधार (वैकल्पिक क्षेत्रों को जोड़ ना, सत्यापन सुधार)।

MINTER: बैक-संगत एक्सटेंशन (नए एंडपॉइंट, डिफ़ॉल्ट के साथ फ़ील्ड)।

मेजर (ब्रेकिंग): संरचना, शब्दार्थ या हटाने वाले क्षेत्रों/समापन बिंदुओं को बदलना।

SemVer 'MEGER की सिफारिश की जाती है। माइनर। कलाकृतियों (SDK/schemas) के लिए PATCH ', जबकि "बाहरी" API संख्या को सरल (v1, v2) बनाया जा सकता है।

3) REST versioning मॉडल

1. यूआरआई के लिए:

'GET/v1/भुगतान/{ id}'

पेशेवरों: पारदर्शी, कैशलेबल, मार्ग के लिए आसान। विपक्ष: प्रलेखन का दोहराव, सूक्ष्म रूप से विकसित करना अधिक कठिन।

2. हेडर में (सामग्री बातचीत):

'स्वीकार करें: आवेदन/vnd। कंपनी। भुगतान। v2 + json '

पेशेवरों: लचीलापन, यूआरएल में कोई "कचरा", मीडिया प्रकार का सुविधाजनक विकास। विपक्ष: ब्राउज़र में डिबग करना अधिक कठिन है, आपको एक अनुशासित क्लाइंट की आवश्यकता है।

3. मनपसंद शीर्षिका में:

'एक्स-एपीआई-संस्करण: 2' (или 'एपी-संस्करण: 2025-09-01')

पेशेवरों: बस स्लुइस पर। विपक्ष: कोई मानकीता नहीं, कैश के साथ सावधान।

4. तिथि-आधारित संस्करण:

फिनटेक/रिपोर्टिंग के लिए अच्छा है: परिवर्तन की पूर्वानुमानित "कटौती" (उदा। त्रैमासिक)।

5. संसाधन/मॉडल Versioning:

सिफारिश: बाहरी एकीकरण के लिए - 'URI vN' + अस्वीकृति/सूर्यास्त हेडर; आंतरिक के लिए - आप 'स्वीकार' या संस्करण हेडर कर सकते हैं, यदि प्रवेश द्वार और मंच इसका समर्थन करते हैं।

4) ग्राफक्यूएल

वरीयता - कोई वैश्विक संस्करण नहीं। क्षेत्र/प्रकार और अवक्षेपण के जोड़ के माध्यम से एवोल्यूशन ('@ deprecated (कारण:... "")').

ब्रेकिंग परिवर्तन - माइग्रेशन गाइड के साथ केवल "बड़ी" विंडो (वर्शन स्कीमा नेमस्पेस) में।

"n + 1" के लिए देखें और मौजूदा क्षेत्रों का अर्थ न बदलें।

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

फील्ड नंबर अपरिवर्तनीय हैं। मिटाए गए क्षेत्रों को 'आरक्षित' के रूप में चिह्नित करें।

सुरक्षित डिफ़ॉल्ट के साथ वैकल्पिक रूप से फ़ील

स्वचालित संगतता जाँच के लिए बफ़ब्रेकिंग/लिंट का उपयोग करें।

संस्करण पैकेज/मॉड्यूल: 'पैकेज भुगतान। v1; '→' भुगतान। v2 '।

6) इवेंट एपीआई (ईडीए)

घटना योजना एक ही संविदा है। इसे स्कीमा रजिस्ट्री (एवरो/JSON-Schema/Protobuf) में स्टोर करें।

विषय और संस्करण: 'भुगतान। v1। अधिकृत ',' भुगतान। v2। अधिकृत '।

परिवर्तन - एक नई प्रकार की घटना या एक नया विषय।

विकास की गारंटी: एलटीएस अवधि के दौरान उपभोक्ताओं के लिए पिछड़ा-संगत।

7) अवक्षेपण नीति और ईओएल

• मूल्यह्रास: चेंजलॉग में लेबल और विनिर्देशों में (OpenAPI/GraphQL SDL), हेडर
• 'डिप्रेशन: ट्रू' और जब संभव हो 'सनसेट: ट्यू, 31 मार्च 2026 00:00 GMT'।
• संचार: ईमेल/पार्टनर पोर्टल, वेबहूक सूचनाएं, रिलीज नोट्स।
• शर्तें: माइनर - 3-6 महीने का समर्थन, मेजर - 9-18 महीने (आलोचना के आधार पर)।
• समय विंडो: "एपीआई वर्शनिंग पॉलिसी" में फिक्स करें।

8) रूटिंग और रिलीज़

गेटवे एपीआई (कोंग/एपिगी/नगिनक्स/दूत): हेडर या मीडियाटाइप द्वारा उपसर्ग '/v1/' द्वारा नियम।

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

कैनरी/ब्लू-ग्रीन/शैडो: ट्रैफिक के 1-5% पर नए संस्करण को रोल करें, मैट्रिक्स और कॉन्ट्रैक्ट त्रुटियों के लॉग की तुलना करें।

फ़ीचर फ़्लैग्स: अनुबंध बदले बिना व्यवहार छुपाएँ.

शून्य-डाउनटाइम माइग्रेशन: मेजर के साथ, डेटा स्कीमा का डुअल-राइट/रीड प्रदान करें।

9) अनुबंध परीक्षण और संगतता नियंत्रण

OpenAPI Diff (या स्वैगर-diff) - जाँचें कि MINTER/PATCH स्कीमा को नहीं तोड़ ते हैं।

वर्णक्रमीय लिंटिंग शैली, आवश्यक मेटाडेटा (संस्करण, मूल्यह्रास)।

उपभोक्ता-संचालित अनुबंध (संधि) - यह सुनिश्चित करता है कि प्रदाता ग्राहकों को नहीं तोड़ ता है।

buf ब्रेकिंग для protobuf।

CI को मेजर को बढ़ाए बिना परिवर्तनों को तोड़ ना चाहिए।

10) प्रलेखन और एसडीके

चश्मा संस्करण: '/docs/api/v1/openapi। json ', '/docs/api/v2/...'।

SemVer और changelog के साथ संस्करण (npm/maven/pypi) द्वारा SDK उत्पन्न करें।

SDK में पदावनत विधियाँ/पदावनत एनोटेशन के साथ चिह्नित करें।

11) संस्करण द्वारा अवलोकन

• आरपीएस/लेटेंसी/त्रुटियाँ प्रति संस्करण ('api _ version' लेबल).
• एंडपॉइंट उपयोग मानचित्र: v1 पर और कौन है?
• अलर्ट: "> अनुबंध बेमेल के कारण 10% 4xx", "पुराने ग्राहक> टी-डेट के बाद एक्स%।"

12) कैचिंग और संस्करण

इन-ट्रांजिट संस्करण सीडीएन कैचबिलिटी में सुधार करता है।

• 'वैरी: स्वीकार करें, एक्स-एपीआई-संस्करण'।
• कैश कुंजी तोड़ ने के लिए MINTER में प्रतिक्रिया के शब्दार्थ को न बदलें।

13) सुरक्षा

संस्करण को JWT में एन्क्रिप्ट या सिलाई न करें - संस्करण अनुरोध द्वारा निर्धारित किया जाता है, टोकन नहीं।

आंतरिक असेंबली संख्या प्रकट न करें। बाहरी संदेशों के लिए "v1/v2" का उपयोग करें।

मेजर में, समीक्षा सत्यापन, सीमा, पीआईआई मास्किंग।

14) प्रवासन और ऑटो-सहायक

प्रकाशित करें "माइग्रेशन गाइड v1 → v2": फील्ड मैपिंग टेबल, नमूना अनुरोध/प्रतिक्रियाएं, किनारे के मामले।

हम ग्राहकों (सीएलआई) के लिए लिंटर्स की पेशकश करते हैं जो पुराने क्षेत्रों को उजागर करते हैं।

बड़े भागीदारों के लिए - दो संस्करणों के साथ सैंडबॉक्स और एक परीक्षण डेटासेट।

15) एंटी-पैटर्न

"अनन्त v1": समय सीमा और उपयोग मेट्रिक्स की कमी।

MINTER/PATCH में छिपे हुए ब्रेकिंग परिवर्तन

"क्वेरी स्ट्रिंग में संस्करण" ('? v = 2 ') - कैश और रीडेबिलिटी को तोड़ ता है।

"एक समापन बिंदु एक सौ झंडा मान है": परीक्षण/दस्तावेज़करना मुश्किल।

16) कार्यान्वयन चेकलिस्ट

1. बाहरी और आंतरिक क्लाइंट के लिए चयनित मॉडल (यूआरआई/स्वीकार/शीर्षिका)।

2. विनिर्देशों और SDK के लिए SemVer, CI में स्वचालित ब्रेकिंग-चेक।

3. मूल्यह्रास/सूर्यास्त नीति और संचार टेम्पलेट।

4. गेटवे रूटिंग + कैनरी, संस्करण द्वारा डैशबोर्ड।

5. महत्वपूर्ण एकीकरण (भुगतान, केवाईसी, रिपोर्टिंग) के लिए सीडीसी/अनुबंध परीक्षण।

6. प्रलेखन/एसडीके/माइग्रेशन गाइड रिलीज के साथ ही प्रकाशित होता है।

7. तारीखों और जिम्मेदार के साथ ईओएल योजना।

17) उदाहरण

17. 1 REST (URI + हेडर)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 सामग्री बातचीत

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 ग्राफक्यूएल (फील्ड डिप्रिक्शन)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 जीआरपीसी (प्रोटोबुफ)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 इवेंट मॉडल

• 'wallet। v1। संतुलन। अपडेट किया गया '
• 'wallet। v2। संतुलन। परिवर्तित '(विस्तारित स्कीमा के साथ नई घटना)

योजनाओं को रजिस्ट्री में संग्रहीत किया जाता है, निर्माता एक ऐसी योजना के साथ घटनाओं को प्रकाशित नहीं करता है जो संगतता का उल्लंघन करता है।

18) संदर्भ iGaming/fintech (अभ्यास)

भुगतान: नए पीएसपी के लिए इनपुट v2 जहां 'स्थिति '/' dince _ couse' बढ़ाया जाता है; प्रवेश द्वार पर, रिपोर्टिंग के लिए v1 v2 मैपिंग।

KYC: MINTER फील्ड 'पेप _ स्क्रीनिंग' जोड़ ता है, क्लाइंट v1, v2 - की आवश्यकता को अनदेखा करते

जिम्मेदार खेल/सीमा: मेजर सीमा मॉडल (दैनिक/साप्ताहिक) को बदल देता है। EOL v1 से पहले रिपोर्टिंग के लिए दोहरा निर्यात।

नियामकों को रिपोर्टिंग: निश्चित संस्करण-तिथियां: 'रिपोर्टिंग-2025-01'।

19) मिनी-पॉलिसी (विकी के लिए उदाहरण)

मॉडल: बाहरी API के लिए - 'URI/vN/'; आंतरिक - 'स्वीकारें:... vN + json 'या' X-API-Version: N '।

SemVer: स्पेसिफिकेशन और SDK को 'N' के रूप में प्रकाशित किया जाता है। नाबालिग। पैच '। मेजर को RFC/ADR की आवश्यकता होती है।

संगतता: MINTER/PATCH - कोई ब्रेकिंग परिवर्तन नहीं। केवल मेजर के माध्यम से तोड़ ना।

मूल्यह्रास/ईओएल: ≥90-दिन की घोषणा; सुर्खियों में सूर्यास्त की तारीख; महत्वपूर्ण ग्राहकों के लिए एलटीएस शाखा।

नियंत्रण: प्रमुख एकीकरण के लिए CI, CDC में OpenAPI diff/buf ब्रेकिंग।

अवलोकन: लेबल 'api _ version' के साथ मेट्रिक्स/लॉग।

रिलीज़: कैनरी 5% ≥ 24h, फिर हरे मेट्रिक्स के साथ 100% तक चरणों में।

परिणाम

Versioning URL में "/v2 "के बारे में नहीं है, लेकिन इस प्रक्रिया के बारे में: विकास के स्पष्ट नियम, स्वचालित संगतता जांच, प्रबंधित रिलीज़ और एकीकरण के लिए सम्मान। एक स्पष्ट नीति दर्ज करें, स्वचालित निगरानी और अवलोकन - और परिवर्तन अब उत्पाद के लिए खतरा नहीं होगा।