Versioning रणनीतियाँ

चार आम तरीक़े

URI versioning (/v1/orders, /v2/orders) सबसे दिखने वाली है और route करना, cache करना, browser में परखना और दस्तावेज़ित करना सबसे आसान; समझौता यह है कि "version" पूरे API पर लागू होता है। Header versioning (API-Version: 2 या कस्टम header) URLs साफ़ रखती है पर कम दिखती है। Media-type versioning (Accept: application/vnd.example.v2+json) content negotiation उपयोग करने वाले REST-शुद्धतावादियों के लिए ठीक है। तारीख़-आधारित versioning (कुछ भुगतान APIs में प्रयुक्त): हर खाता उस API तारीख़ पर टिका रहता है जब वह शुरू हुआ (API-Version: 2026-01-10), और तोड़ने वाले बदलाव नए दिनांकित versions के रूप में आते हैं जिन्हें clients तैयार होने पर चुनते हैं। जो भी चुनें, version कम रखें: जोड़ने वाले बदलाव चुनें, major version सिर्फ़ तोड़ने वाले बदलावों के लिए बढ़ाएँ, और समर्थित versions की संख्या कम रखें।

तरीक़ों की तुलना

अपने दर्शकों और tooling से चुनें, फिर चुनाव दस्तावेज़ित करें।

Style          Example                                  Pros                         Cons
URI            GET /v2/orders                           visible, easy routing/cache  whole-API versions
Header         API-Version: 2                           clean URLs                   hidden, harder to test
Media type     Accept: application/vnd.x.v2+json        content-negotiation purity   tooling/caching friction
Date-based     API-Version: 2026-01-10                  fine-grained, gradual opt-in complex to implement

तारीख़-आधारित version चुनना, चलाकर

मैंने यह सादा-Python उदाहरण चलाया। जारी versions की सूची दी हो तो 2025-12-31 का अनुरोध उस तारीख़ पर या उससे पहले जारी सबसे नया version (2025-06-15) पाता है; 2026-10-01 को 2026-01-10 मिलता है; पहली release से पहले की तारीख़ को None मिलता है।

import hmac, hashlib, json, time, bisect

VERSIONS = ["2024-03-01", "2025-06-15", "2026-01-10"]
def pick(requested):
    i = bisect.bisect_right(VERSIONS, requested)
    return VERSIONS[i - 1] if i else None
print(pick("2025-12-31"), pick("2026-10-01"), pick("2023-01-01"))

Output:

2025-06-15 2026-01-10 None

त्वरित जाँच: URI versioning का मुख्य लाभ क्या है?

• इसे दस्तावेज़ की ज़रूरत नहीं
• यह version पूरी तरह छिपाता है
• Version दिखाई देता है और route, cache व test करना आसान है
• यह proxies को नहीं दिखता