मुख्य API versioning रणनीतिहरू के के हुन्, र एउटा version कसरी deprecate गर्नुहुन्छ?

Question

IT Interview Practice · Accepted Answer

Versioning ले तपाईंलाई हालका client हरू नबिगारी **breaking change** सँग एउटा API विकास गर्न दिन्छ। तीनवटा मुख्य रणनीति छन्, साथै एउटा deprecation प्रक्रिया।

## तीनवटा रणनीति

**1. URI versioning** — version path मा हुन्छ।
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
सबैभन्दा सरल र देखिने; route, cache, र browser मा test गर्न सजिलो। बेफाइदा: यसले प्राविधिक रूपमा "URI ले एउटा resource पहिचान गर्छ" भन्ने कुरा उल्लङ्घन गर्छ (उही user को अब दुई URL छन्)। यो सबैभन्दा सामान्य छनोट हो (GitHub, ऐतिहासिक रूपमा Stripe)।

**2. Custom header versioning** — version एउटा header मा यात्रा गर्छ।
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
URL सफा राख्छ तर browser मा अदृश्य हुन्छ र cache गर्न गाह्रो हुन्छ।

**3. Media-type (content negotiation) versioning** — version `Accept` मा।
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
सबैभन्दा "RESTful" (resource URL स्थिर रहन्छ; यसको representation मात्र version हुन्छ), तर consumer हरूका लागि सबैभन्दा कम पहुँचयोग्य।

## breaking भनेको के हो

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
Breaking change लाई मात्र नयाँ version चाहिन्छ; non-breaking change हरू हालको version मा थप्नुहोस्।

## Deprecation प्रक्रिया

1. doc र changelog मा मितिहरूसहित **घोषणा गर्नुहोस्**।
2. header हरूसँग **runtime मा सङ्केत दिनुहोस्** ताकि client हरूले प्रोग्रामेटिक रूपमा थाहा पाऊन्:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. पुरानो version को प्रयोग **अनुगमन गर्नुहोस्** र बाँकी caller हरूलाई सम्पर्क गर्नुहोस्।
4. प्रयोग शून्यको नजिक झरेपछि मात्र **Sunset** गर्नुहोस्।

## यो किन महत्त्वपूर्ण छ

Interviewer हरूले यो तपाईंले production मा एउटा API लाई त्यसमा निर्भर client हरू नबिगारी बढाउन सक्नुहुन्छ कि भनेर हेर्न सोध्छन् — एउटा वास्तविक सञ्चालन चिन्ता, सैद्धान्तिक होइन। सबैभन्दा बलिया जवाफहरूले दुई भिन्नता गर्छन्: पहिलो, कि **धेरैजसो change हरू non-breaking हुन्छन्** र version bump गर्नै हुँदैन (additive change हरू हालको version मा जान्छन्), versioning लाई साँच्चै breaking change का लागि मात्र राख्दै; र दोस्रो, कि *रणनीति* भन्दा *प्रक्रिया* बढी महत्त्वपूर्ण हुन्छ — `Deprecation`/`Sunset` header र प्रयोग अनुगमनसहितको स्पष्ट deprecation timeline नै वास्तवमा consumer हरूलाई जोगाउने कुरा हो। URI versioning व्यवहारमा यसको दृश्यता र tooling समर्थनका लागि जित्छ, तर trade-off हरू (header र media-type ले URL स्थिर राख्छन् र बढी RESTful हुन्छन्, discoverability को मूल्यमा) थाहा हुनाले तपाईं केवल `/v1/` cargo-cult गर्नुभन्दा design space बुझ्नुहुन्छ भन्ने देखाउँछ।

तीनवटा रणनीति

breaking भनेको के हो

Deprecation प्रक्रिया

यो किन महत्त्वपूर्ण छ

सम्बन्धित प्रश्नहरू