समय-सीमा, संवाद और उपयोग ट्रैकिंग

कोई हैरानी नहीं

Clients को पर्याप्त समय दें (सार्वजनिक APIs अक्सर 6 से 12 महीने या ज़्यादा देते हैं; आंतरिक कम) और योजना पहले से प्रकाशित करें: घोषणा की तारीख़, नए version की उपलब्धता, deprecation की शुरुआत, sunset की तारीख़। कई माध्यमों से संवाद करें: changelog, developer email, dashboard में banner, response headers और कभी-कभी brownouts (छोटे निर्धारित व्यवधान जो सोते clients का ध्यान खींचें)। प्रति client उपयोग ट्रैक करें (API key, user agent) ताकि बचे सबसे भारी उपयोगकर्ताओं से व्यक्तिगत रूप से संपर्क कर सकें। पहले/बाद के उदाहरणों वाला migration guide, बदले fields का नक़्शा, और नए version के लिए test या sandbox access दें। तारीख़ आने पर उलझाने वाले error की जगह (guide से जुड़ी problem body के साथ) साफ़ 410 Gone लौटाएँ। महत्वपूर्ण clients तैयार न हों और आपकी नीति अनुमति दे तो तारीख़ बढ़ाएँ; उसे चुपचाप कभी न हटाएँ।

Deprecation योजना

इसे लिख लें और पहली घोषणा के साथ साझा करें।

2026-10-01  v2 GA; v1 marked Deprecated (headers, docs, changelog, email)
2026-11-15  migration guide + sandbox; usage report per client sent monthly
2026-12-01  brownout #1: v1 returns 503 for 15 minutes
2026-12-15  brownout #2: 1 hour; contact remaining top callers directly
2026-12-31  Sunset: v1 returns 410 Gone with a link to the guide
2027-01-31  v1 code and routes removed

बंद करने से पहले मापें

मापदंड उपयोग करें "पिछले 7 दिनों में v1 पर अनुरोध, client के अनुसार"। यह शून्य (या सिर्फ़ वे clients जिन्हें आप संपर्क कर चुके) होने पर विदाई सुरक्षित है।

त्वरित जाँच: Sunset तारीख़ के बाद विदा हुए endpoint को क्या लौटाना चाहिए?

• ख़ाली डेटा के साथ 200
• उपयोगी problem body के साथ 410 Gone
• कोई random 500
• कुछ नहीं, connection बंद करें