اہم API versioning حکمتِ عملیاں کون سی ہیں، اور آپ کسی version کو کیسے deprecate کرتے ہیں؟

Question

IT Interview Practice · Accepted Answer

Versioning آپ کو موجودہ clients کو توڑے بغیر کسی API کو **breaking changes** کے ساتھ ارتقا دینے دیتی ہے۔ تین مرکزی حکمتِ عملیاں ہیں، اور ساتھ میں ایک 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 کے دو URLs ہیں)۔ یہ کہیں زیادہ عام انتخاب ہے (GitHub، Stripe تاریخی طور پر)۔

**2. Custom header versioning** — version ایک header میں سفر کرتا ہے۔
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
URLs کو صاف رکھتا ہے مگر 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 ہوتا ہے)، مگر صارفین کے لیے سب سے کم قابلِ رسائی۔

## 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 changes کو نئے version کی ضرورت ہے؛ non-breaking changes موجودہ میں شامل کریں۔

## Deprecation عمل

1. docs اور changelog میں تاریخوں کے ساتھ **اعلان کریں**۔
2. runtime پر headers کے ساتھ **اشارہ دیں** تاکہ clients پروگرام کے ذریعے متوجہ ہوں:
```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 کے استعمال کی **نگرانی کریں** اور باقی ماندہ callers سے رابطہ کریں۔
4. استعمال تقریباً صفر پر گرنے کے بعد ہی **Sunset کریں**۔

## یہ کیوں اہم ہے

انٹرویو لینے والے یہ اس لیے پوچھتے ہیں کہ دیکھ سکیں کہ آیا آپ production میں کسی API کو ان clients کو توڑے بغیر بڑھا سکتے ہیں جو اس پر انحصار کرتے ہیں — ایک حقیقی آپریشنل تشویش، نظری نہیں۔ سب سے مضبوط جوابات دو تمیزیں کرتے ہیں: پہلی، کہ **زیادہ تر تبدیلیاں non-breaking** ہیں اور انہیں بالکل version bump نہیں کرنا چاہیے (اضافی تبدیلیاں موجودہ version میں جاتی ہیں)، versioning کو حقیقی breaking changes کے لیے محفوظ رکھتے ہوئے؛ اور دوسری، کہ *حکمتِ عملی* سے *عمل* زیادہ اہم ہے — `Deprecation`/`Sunset` headers اور استعمال کی نگرانی کے ساتھ ایک واضح deprecation ٹائم لائن ہی وہ چیز ہے جو دراصل صارفین کی حفاظت کرتی ہے۔ URI versioning اپنی نمایاں پہچان اور tooling سپورٹ کی وجہ سے عملی طور پر جیت جاتی ہے، لیکن trade-offs کو جاننا (header اور media-type URLs کو مستحکم رکھتے ہیں اور زیادہ RESTful ہیں، مگر قابلِ دریافت ہونے کی قیمت پر) یہ ظاہر کرتا ہے کہ آپ ڈیزائن اسپیس کو سمجھتے ہیں نہ کہ محض `/v1/` کی نقل کرتے ہیں۔

تین حکمتِ عملیاں

breaking کیا شمار ہوتا ہے

Deprecation عمل

یہ کیوں اہم ہے

متعلقہ سوالات