रिसोर्स · 33
क्लाइंट खोए बिना API कॉन्ट्रैक्ट बनाएं
रिक्वेस्ट, रिस्पॉन्स और एरर बताएं; वर्शन टेस्ट करें और वेबहुक को दोबारा चलाने के लिए सुरक्षित बनाएं।
अपडेटेड · 5 min
यह गाइड क्या पाने में मदद करती है
- कॉन्ट्रैक्ट लिखें
- एरर साफ़ करें
- कम्पैटिबिलिटी टेस्ट करें
- रिटायरमेंट प्लान करें
जल्दी से चेक करें
- कौन से क्लाइंट हर ऑपरेशन का इस्तेमाल करते हैं?
- क्या एरर के टाइप स्टेबल और स्टेटस एक जैसे होते हैं?
- क्या कोई पुराना क्लाइंट बदलाव को बर्दाश्त कर सकता है?
- क्या रीट्राई किसी एक्शन को डुप्लिकेट कर सकते हैं?
- रिटायरमेंट की घोषणा और वेरिफिकेशन कैसे किया जाएगा?
स्टेप-बाय-स्टेप तरीका
- 1
इन्वेंटरी कंज्यूमर
ऑपरेशन, क्लाइंट, इस्तेमाल, वर्शन और ओनर की लिस्ट बनाएं। किसी फ़ील्ड को बदलने से पहले देखे गए इस्तेमाल को अंदाज़ों से अलग करें।
डिलीवरेबल: कॉन्ट्रैक्ट डिपेंडेंसी मैप।
- 2
रिक्वेस्ट और रिस्पॉन्स बताएं
स्कीमा, असली उदाहरण, सफलता और नाकामयाबी के जवाबों के साथ एक OpenAPI डिस्क्रिप्शन बनाए रखें। इसे चल रही सर्विस के साथ चेक करें।
डिलीवरेबल: वर्शन वाला कॉन्ट्रैक्ट और कन्फर्मेंस टेस्ट।
- 3
गलतियों को स्टेबल करें
HTTP स्टेटस का इस्तेमाल उनके सिमेंटिक्स के हिसाब से करें और, जहाँ मददगार हो, RFC 9457 के तहत एक डॉक्यूमेंटेड प्रॉब्लम टाइप का इस्तेमाल करें। सीक्रेट्स को डिटेल में न बताएं।
डिलीवरेबल: टेस्ट किया गया एरर कैटलॉग।
- 4
बदलाव को क्लासिफ़ाई करें
ज़रूरी फ़ील्ड, टाइप, वैल्यू, बिहेवियर, टाइमआउट और पेजिनेशन को इंस्पेक्ट करें। पुराने क्लाइंट्स को नए वर्शन के साथ रिप्रेजेंटेटिव केस के साथ टेस्ट करें।
डिलीवरेबल: कम्पैटिबिलिटी मैट्रिक्स और वर्शन का फ़ैसला।
- 5
नोटिफ़िकेशन को मज़बूत बनाएं
वेबहुक के लिए, ऑथेंटिकेशन, अनऑर्डर्ड डिलीवरी, डुप्लीकेट और रीट्राई प्लान करें। जहाँ रिपीटिशन मुमकिन हो, वहाँ प्रोसेसिंग को आइडेम्पोटेंट बनाएं।
डिलीवरेबल: रीप्ले और एक्नॉलेजमेंट सिनेरियो।
- 6
एक एग्जिट पाथ के साथ रिलीज़
माइग्रेशन नोट्स, साथ रहने का समय और कॉन्टैक्ट्स पब्लिश करें। पुराने वर्शन के इस्तेमाल को मापें और प्रभावित कंज्यूमर्स की जांच करने के बाद ही रिटायर करें।
डिलीवरेबल: माइग्रेशन प्लान और रिटायरमेंट एविडेंस।
मैनेजमेंट इंडिकेटर
| इंडिकेटर | यह क्या मापता है | पहला एक्शन |
|---|---|---|
| कॉन्ट्रैक्ट | बताए गए ऑपरेशन और सर्विस बिहेवियर से मैच करना | फर्क ठीक करना |
| कम्पैटिबिलिटी | बदलाव से पहले टेस्ट किए गए रिप्रेजेंटेटिव क्लाइंट | मिसिंग केस जोड़ना |
| गलतियाँ | बिना सेंसिटिव डेटा वाले टाइप को डॉक्यूमेंट करना | मैसेज और स्कीमा को बदलना |
| माइग्रेशन | ओनर के साथ पुराने वर्शन का इस्तेमाल | बाकी क्लाइंट की मदद करना |
आम गलतियाँ
- यह मानकर कि सिर्फ़ वर्शन नंबर से कम्पैटिबिलिटी बनी रहती है
- सिर्फ़ 200 रिस्पॉन्स को डॉक्यूमेंट करना
- एरर में इंटरनल ट्रेस या सीक्रेट रिटर्न करना
- यह मानकर कि वेबहुक एक बार और क्रम से आते हैं
अक्सर पूछे जाने वाले सवाल
क्या OpenAPI टेस्टिंग की जगह लेता है?
नहीं। असली रिस्पॉन्स और कंज्यूमर की ज़रूरतों से डिस्क्रिप्शन की तुलना करें।
क्या हर बदलाव के लिए नए वर्शन की ज़रूरत होती है?
नहीं। क्लाइंट के असर और कॉन्ट्रैक्ट बिहेवियर से तय करें; इनकम्पैटिबल बदलावों के लिए एक साफ़ प्लान की ज़रूरत होती है।
टाइप की गई गलतियाँ क्यों?
वे क्लाइंट को समस्याओं को पहचानने और कोई एक्शन चुनने का एक स्टेबल तरीका देते हैं।
ऑफ़िशियल रेफ़रेंस
रेफ़रेंस इस तरीके को सपोर्ट करते हैं। अपने कॉन्टेक्स्ट के हिसाब से चेक को एडजस्ट करें; वे सर्टिफ़िकेशन नहीं हैं। ओरिजिनल रेफ़रेंस टाइटल और सोर्स डॉक्यूमेंट दूसरी भाषा में हो सकते हैं।
