रिस्पॉन्स कॉन्ट्रैक्ट कम्पेरेटर — ब्रेकिंग चेंज पहचानें

API कॉन्ट्रैक्ट टेस्टिंग क्या है?

API कॉन्ट्रैक्ट किसी इंटरफ़ेस का सहमत विवरण है — उसके एंडपॉइंट, पैरामीटर, रिक्वेस्ट व रिस्पॉन्स स्कीमा और स्टेटस कोड — जो आमतौर पर OpenAPI दस्तावेज़ के रूप में लिखा जाता है। कॉन्ट्रैक्ट टेस्टिंग सर्विस के वास्तविक रिस्पॉन्स की उस विवरण से तुलना करती है, ताकि बदला हुआ फ़ील्ड नाम या टाइप दूसरी तरफ़ को तोड़ने से पहले प्रोड्यूसर या कंज़्यूमर के पास पकड़ा जाए।

गाइड पढ़ें: API टेस्टिंग क्या है? REST API कैसे टेस्ट करें

रिस्पॉन्स कॉन्ट्रैक्ट कम्पेरेटर कैसे इस्तेमाल करें

अपेक्षित कॉन्ट्रैक्ट पेस्ट करें: कोई जाँचा-परखा उदाहरण रिस्पॉन्स या JSON Schema (JSON या YAML)।
दाईं ओर असली रिस्पॉन्स (या नई स्कीमा) पेस्ट करें।
मोड को auto-detect पर रहने दें, या ख़ुद example/schema मोड चुन लें।
फ़ैसला और गंभीरता के क्रम में लगी तालिका पढ़ें; breaking पंक्तियों के लिए वर्शन बढ़ाना या सुधार करना ज़रूरी है।
अगर request ids या timestamps जैसे fields हर call पर बदलते हैं और contract का हिस्सा नहीं हैं, तो उन्हें "ये paths अनदेखा करें" में लिखें (या volatile-field विकल्प चुनें)।

रिस्पॉन्स कॉन्ट्रैक्ट कम्पेरेटर की खूबियाँ

तीन मोड: उदाहरण बनाम रिस्पॉन्स, JSON Schema बनाम रिस्पॉन्स, और स्कीमा बनाम स्कीमा
Breaking: हटाए गए फ़ील्ड, type के बदलाव, वैल्यू → null, नई ज़रूरी प्रॉपर्टी, हटाई गई enum वैल्यू, required → optional
जोखिम भरे: enum का बढ़ना, format/pattern के बदलाव, integer → number, कड़े किए गए constraint, नए oneOf/anyOf विकल्प
सुरक्षित: जोड़े गए वैकल्पिक फ़ील्ड और ढीले किए गए constraint
ऐरे के आइटम अपेक्षित आइटम के आकार से तुलना किए जाते हैं और दोहराए गए अंतर एक पंक्ति में समेट दिए जाते हैं
गिनती सहित फ़ैसला और डाउनलोड की जा सकने वाली अंतर तालिका (path, बदलाव, अपेक्षित, असली)
वैकल्पिक exclusions: अनदेखा करने के paths ($.a.b, [*], *, ** या सिर्फ़ key का नाम) और ids, timestamps, tokens व cursors जैसे volatile fields का switch — अनदेखे अंतर दिखाए जाते हैं, छिपाए नहीं जाते

रिस्पॉन्स कॉन्ट्रैक्ट कम्पेरेटर का उदाहरण

बैकएंड में बदलाव के बाद ऑर्डर रिस्पॉन्स

इनपुट:

Expected: { "id": 1042, "customer": { "email": "layla@example.com" }, "total": 39.98, "createdAt": "2026-09-01T10:00:00Z" }
Actual:   { "id": "1042", "customer": { "tier": "gold" }, "total": null, "createdAt": "01/09/2026" }

आउटपुट:

Verdict: Breaking — 3 breaking changes and 1 risky.
breaking · $.id · type-change: Type changed from integer to string.
breaking · $.customer.email · removed-field: Field "email" is missing from the response.
breaking · $.total · value-to-null: Expected a number but the response returned null.
risky · $.createdAt · format-change: Expected a date-time formatted string but got a plain string.
safe · $.customer.tier · added-field: New field "tier" was added.

रिस्पॉन्स कॉन्ट्रैक्ट कम्पेरेटर के बारे में अक्सर पूछे जाने वाले सवाल

breaking किसे माना जाता है?

हटाए गए फ़ील्ड, type के बदलाव, कोई वैल्यू जो null हो गई, नई ज़रूरी प्रॉपर्टी, हटाई गई enum वैल्यू और वे फ़ील्ड जिनकी अब गारंटी नहीं रही (required → optional)।

जोखिम भरा क्या है?

ऐसे बदलाव जिन्हें सख़्त consumer अस्वीकार कर सकते हैं: नई enum वैल्यू, format या pattern के बदलाव, integer का ढीला होकर number बन जाना, कड़े किए गए constraint या नए oneOf/anyOf विकल्प।

सुरक्षित क्या है?

जोड़े गए वैकल्पिक फ़ील्ड और ढीले किए गए constraint — जो consumer अनजान फ़ील्ड अनदेखा करते हैं, वे बिना रुकावट काम करते रहते हैं।

क्या मैं दो स्कीमा की तुलना कर सकता हूँ?

हाँ। पुरानी JSON Schema को अपेक्षित और नई को असली की जगह पेस्ट करें; टूल स्कीमा-बनाम-स्कीमा मोड अपने आप पहचान लेता है, या आप मोड सिलेक्टर से चुन सकते हैं।

example मोड में ऐरे की तुलना कैसे होती है?

असली ऐरे के हर आइटम (अधिकतम 25) की तुलना अपेक्षित ऐरे के पहले आइटम से की जाती है, और दोहराए गए अंतर एक ही पंक्ति में समेट दिए जाते हैं।

क्या मैं हर response पर बदलने वाले fields बाहर रख सकता हूँ?

हाँ। अनदेखा करने वाले paths हर पंक्ति में एक लिखें — $.meta.requestId, $.items[*].etag, **.debug, या updatedAt जैसा सिर्फ़ key का नाम जो कहीं भी मेल खाए — या ids, timestamps, tokens, cursors और versions के लिए "Volatile fields भी अनदेखा करें" चुनें। Verdict उनके बिना निकाला जाता है, और हर अनदेखा अंतर फिर भी notes में दिखता है, और अगर उनमें से कोई breaking होता तो चेतावनी दी जाती है।

तकनीकी नोट्स

example मोड हर वैल्यू का type (null, boolean, integer, number, string, array, object) और स्ट्रिंग का format (date-time, date, uuid, email, url) अनुमानित करता है, ताकि तारीख़ का आकार बदलने पर उसे चुपचाप स्वीकार करने के बजाय जोखिम भरा बताया जाए। असली ऐरे के हर आइटम की तुलना अपेक्षित पहले आइटम से होती है, और कई आइटम में मिलने वाले एक जैसे अंतर [] वाले path के साथ एक ही बार बताए जाते हैं।

schema मोड JSON Schema वैलिडेटर का ही दोबारा इस्तेमाल करता है और keyword उल्लंघनों को गंभीरता से जोड़ता है: required → breaking, type → breaking, additionalProperties → सुरक्षित (जोड़ा गया फ़ील्ड), enum/format/pattern/constraint → जोखिम भरा। स्कीमा-बनाम-स्कीमा मोड दोनों स्कीमा को साथ-साथ खंगालता है, जिसमें nullable, enum, format, constraint, required सूचियाँ, additionalProperties, items और composition keyword शामिल हैं।

संदर्भ

OpenAPI SpecificationOpenAPI InitiativeREST API के वर्णन का मानक: पाथ, ऑपरेशन, पैरामीटर, स्कीमा, रिस्पॉन्स और सिक्योरिटी स्कीम।
JSON Schema SpecificationJSON SchemaJSON दस्तावेज़ की संरचना का वर्णन और वैलिडेशन करने की शब्दावली (टाइप, आवश्यक प्रॉपर्टी, फ़ॉर्मेट)।
RFC 9110: HTTP SemanticsIETF · 2022HTTP मेथड, हेडर फ़ील्ड, स्टेटस कोड और कंटेंट निगोशिएशन के अर्थ, वायर वर्ज़न से स्वतंत्र।