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

Source: https://www.geekswithgeeks.com/hi/api-design/dep-timeline-comms

> यथार्थवादी deprecation समय-सीमा बनाएँ, कई माध्यमों से संवाद करें और ट्रैक करें कि पुराना version अब भी कौन उपयोग करता है।

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

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 योजना

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

```text
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 जिन्हें आप संपर्क कर चुके) होने पर विदाई सुरक्षित है।

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

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

*Answer:* उपयोगी problem body के साथ 410 Gone. 410 साफ़ बताता है कि resource स्थायी रूप से जा चुका है और migration मदद की ओर इशारा कर सकता है।