آپ APIs کو version کیسے کرتے ہیں اور services کے درمیان backward compatibility کو کیسے برقرار رکھتے ہیں?

Question

Accepted Answer

کیونکہ services آزادانہ طور پر deploy ہوتی ہیں، آپ کبھی یہ فرض نہیں کر سکتے کہ callers بیک وقت upgrade کریں گے۔ **API versioning** اور **backward compatibility** سے producers موجودہ consumers کو break کیے بغیر evolve کر سکتے ہیں۔

## Versioning کی حکمت عملی

| حکمت عملی | مثال |
|---|---|
| URI path | `GET /v2/orders/42` |
| Header | `Accept: application/vnd.api.v2+json` |
| Schema evolution | fields شامل کریں، کبھی remove/rename نہ کریں |

## Additive (non-breaking) تبدیلیوں کو ترجیح دیں

```text
NON-BREAKING (safe):
  ✓ add a new optional field
  ✓ add a new endpoint
  ✓ add a new enum value (if clients tolerate unknowns)

BREAKING (needs a new version):
  ✗ remove or rename a field
  ✗ change a type or make a field required
  ✗ change semantics of an existing field
```

## Protobuf اس میں سہائک ہے

```proto
message Order {
  string id = 1;
  double total = 2;
  string currency = 3;  // NEW field 3 — old clients ignore it safely
}
```

Field numbers، نہ کہ names، wire format کو define کرتے ہیں، اس لیے fields شامل کرنا backward compatible ہے۔

## Lifecycle

```text
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
```

## خطرہ

کبھی کوئی version remove نہ کریں جبکہ اس پر حقیقی traffic ہو۔ Retire کرنے سے پہلے usage کو track کریں۔

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

آزادانہ deployability تب ہی کام کرتی ہے جب ایک producer کوئی تبدیلی ship کر سکے بغیر ہر consumer کی release کو coordinate کیے۔

Additive change کے لیے design کرنا اور migration کے دوران پرانے versions کو support کرنا وہی ہے جو اس آزادی کو preserve کرتا ہے بجائے fragile big-bang upgrades کے۔

URI path	`GET /v2/orders/42`
Header	`Accept: application/vnd.api.v2+json`
Schema evolution	fields شامل کریں، کبھی remove/rename نہ کریں