API مائیگریشن گائیڈ کیسے لکھیں (بشمول حقیقی دنیا کی مثالیں)

جب کوئی API نیا ورژن جاری کرتا ہے، تو اسے استعمال کرنے والے تمام ڈویلپرز کو اپنا کوڈ اپ ڈیٹ کرنا ہوگا۔ اگر آپ کو صرف ایک چینج لاگ انٹری ملتی ہے جس میں کہا گیا ہے کہ "صفحہ بندی اب ایک کرسر استعمال کرتی ہے”، تو آپ کو خود ہی مسئلہ کا پتہ لگانا پڑے گا۔ ان میں سے کچھ اسے صحیح سمجھ سکتے ہیں، دوسروں کو نہیں مل سکتا ہے۔

اسی لیے ڈویلپرز کو API منتقلی گائیڈ کی ضرورت ہوتی ہے۔ یہ آپ کو بتاتا ہے کہ کیا تبدیل ہوا ہے، آپ کو اپنے کوڈ میں کون سی اپ ڈیٹس کرنے کی ضرورت ہے، اور آپ کو انہیں کب تک اپ ڈیٹ کرنے کی ضرورت ہے۔

اس ٹیوٹوریل میں، آپ سیکھیں گے کہ شروع سے آخر تک API منتقلی گائیڈ کیسے لکھنا ہے۔ میں v1 سے v2 تک جانے کے لیے ایک نمونہ انوینٹری API استعمال کروں گا اور ایک گائیڈ جمع کروں گا۔ آخر میں، آپ کے پاس ایک مکمل گائیڈ اور ڈھانچہ ہوگا جسے دوسرے APIs کے لیے دوبارہ استعمال کیا جا سکتا ہے۔

اس ٹیوٹوریل کا مقصد تکنیکی مصنفین، اپنے APIs کی دستاویز کرنے والے ڈویلپرز، اور DevRel صارفین کے لیے ہے جنہیں دوسرے ڈویلپرز کو API تبدیلیوں کی وضاحت کرنے کی ضرورت ہے۔

انڈیکس

شرطیں

پیروی کرنے کے لیے آپ کو API ماہر بننے کی ضرورت نہیں ہے، لیکن آپ کو بنیادی باتوں کو سمجھنا چاہیے:

  • بنیادی علم REST APIs: آپ کو یہ جاننے کی ضرورت ہے کہ اختتامی نقطہ کیا ہے، درخواست کے ہیڈر کیا کرتے ہیں، اور 401 اور 404 جیسے اسٹیٹس کوڈ کا کیا مطلب ہے۔
  • جاوا اسکرپٹ کو آرام سے پڑھنا: کوڈ سے پہلے اور بعد کی مثالیں جاوا اسکرپٹ کا استعمال کرتی ہیں۔ fetch() فنکشن آپ کو انہیں چلانے کی ضرورت نہیں ہے، لیکن آپ کو ہر خصوصیت کی پیروی کرنے کے قابل ہونا چاہئے۔
  • واقف قیمت میں کمی: آپ اپنی مائیگریشن گائیڈ مارک ڈاؤن میں لکھیں گے، وہی فارمیٹ جو زیادہ تر دستاویزی سائٹس اور GitHub READMEs کے ذریعے استعمال کیا جاتا ہے۔

میمو: انوینٹری API اس ٹیوٹوریل کے لیے بنایا گیا ایک نمونہ API ہے، لہذا آپ کو اس کے لیے انسٹال یا سائن اپ کرنے کی ضرورت نہیں ہے۔ آپ کو صرف ایک ٹیکسٹ ایڈیٹر کی ضرورت ہے۔

API مائیگریشن گائیڈ کیا ہے؟

API مائیگریشن گائیڈ ایک دستاویز ہے جو ڈویلپرز کو دکھاتی ہے کہ اپنے کوڈ کو API کے ایک ورژن سے دوسرے ورژن میں کیسے منتقل کریں۔ وضاحت کریں کہ کیا تبدیل ہوا ہے، کس چیز کو اپ ڈیٹ کرنے کی ضرورت ہے، اور تبدیلیاں کب ہونے والی ہیں۔

لوگ عام طور پر تبدیلی کے نوشتہ جات اور ریلیز نوٹس کے ساتھ منتقلی کے رہنما کو الجھاتے ہیں۔ کیونکہ ہر کوئی تبدیلی کی بات کر رہا ہے۔ فرق اس بات میں ہے کہ ان کا مقصد کیا ہے۔

تبدیلی کا لاگ ریکارڈ کرتا ہے کہ کیا تبدیل ہوا ہے، ریلیز نوٹس اس بات کا اعلان کرتے ہیں کہ نیا کیا ہے، اور منتقلی کے رہنما ڈویلپرز کو بتاتے ہیں کہ ان تبدیلیوں کی وجہ سے ان کے کوڈ میں کیا اپ ڈیٹ کرنا ہے۔

تاریخ کو تبدیل کریں۔ جاری نوٹ مائیگریشن گائیڈ
مقصد ہر ورژن میں تمام تبدیلیوں کو ریکارڈ کرتا ہے۔ ریلیز میں نئی ​​خصوصیات کا اعلان ڈویلپرز کو ان کے کوڈ کو اپ ڈیٹ کرنے میں مدد کریں۔
آستین تمام بڑی اور چھوٹی تبدیلیاں جھلکیاں اور نئی خصوصیات تبدیلیاں جن کے لیے ڈویلپر کی کارروائی کی ضرورت ہوتی ہے۔
فارمیٹ ورژن کے لحاظ سے گروپ بندی کی فہرست ایک مختصر خلاصہ یا پیشکش کوڈ کے ساتھ مرحلہ وار ہدایات
جواب "کیا بدلا ہے؟” "نیا کیا ہے؟” "مجھے کیا کرنا چاہیے؟”

لہذا اگر کوئی ڈویلپر تبدیلی لاگ کو پڑھتا ہے لیکن پھر بھی نہیں جانتا ہے کہ کوڈ میں کیا تبدیل کرنا ہے، تو یہ اس بات کی علامت ہے کہ اسے منتقلی کے رہنما کی ضرورت ہے۔ اکثر ایسا ہوتا ہے جب کسی ریلیز میں بریکنگ تبدیلیاں ہوتی ہیں۔

کیا ایک اہم تبدیلی سمجھا جاتا ہے؟

بریکنگ تبدیلیاں API تبدیلیاں ہیں جن کی وجہ سے موجودہ کوڈ ڈویلپرز کو بغیر کسی تبدیلی کے کام کرنا بند کر سکتا ہے۔ مثال کے طور پر، اگر API میں تبدیلی کی وجہ سے کسی کا انضمام کام کرنا چھوڑ دیتا ہے، تو یہ ایک بری تبدیلی ہے۔

یہی وجہ ہے کہ API ٹیمیں عام طور پر نئے بڑے ورژنز میں بریکنگ تبدیلیاں جاری کرتی ہیں، جیسے کہ v1 سے v2 میں منتقل ہونا۔ بہت سی ٹیمیں Semantic Versioning (SemVer) کی پیروی کرتی ہیں، ایک نمبر دینے والا نظام جس کے درج ذیل ورژن ہیں: 2.4.1 یہ تین حصوں پر مشتمل ہے: بڑا، معمولی اور پیچ۔ اگر آپ کی تبدیلیاں موجودہ کوڈ کو توڑ دیتی ہیں، تو آپ دیکھیں گے کہ آپ کا API v1.1 کے بجائے v1 سے v2 تک چھلانگ لگاتا ہے، کیونکہ کلیدی نمبر بڑھتے جائیں گے۔

API کا حصہ اہم تبدیلی اہم تبدیلیاں
اختتامی نقطہ اختتامی نقطہ کو ہٹا دیں۔ نیا اختتامی نقطہ شامل کریں۔
بیٹری فیلڈ کی قسموں کا نام تبدیل کریں، ہٹائیں یا تبدیل کریں، جیسے کہ نمبرز سٹرنگ بنتے ہیں۔ جواب میں نیا فیلڈ شامل کریں۔
پیرامیٹر اختیاری پیرامیٹرز کو مطلوبہ بنائیں نئے اختیاری پیرامیٹرز شامل کریں۔
ثبوت ڈویلپرز API کیز بھیجنے کا طریقہ تبدیل کریں، جیسے API کلید کو URL سے ہیڈر میں منتقل کرنا پرانا طریقہ کام کرتے ہوئے توثیق کرنے کا نیا طریقہ شامل کریں۔
غلطی غلطی کے جوابات کی ساخت کو تبدیل کریں، جیسے کہ ٹیکسٹ میسجز کا آبجیکٹ بننا موجودہ ایرر آبجیکٹ میں نئے فیلڈز شامل کریں، جیسے کہ درخواست کی شناخت
صفحہ بندی نتائج کو صفحات میں تقسیم کرنے کا طریقہ تبدیل کریں، جیسے کہ صفحہ نمبر کرسر بنتے ہیں۔ فی صفحہ اشیاء کی زیادہ سے زیادہ تعداد میں اضافہ کریں۔

کچھ تبدیلیاں درمیان میں ہیں۔ مثال کے طور پر، جواب میں ایک نیا فیلڈ شامل کرنے سے زیادہ تر معاملات میں کوئی مسئلہ نہیں ہوگا، لیکن یہ ان ایپس کو توڑ سکتا ہے جو نامعلوم فیلڈز کو مسترد کرنے کے لیے سیٹ ہیں۔ نئے ایرر اسٹیٹس کوڈز ڈویلپرز کو چوکس کر سکتے ہیں اگر ان کا کوڈ صرف پرانی غلطیوں کو ہینڈل کرتا ہے۔

اگر شک ہو تو تبدیلی کو بریکنگ سمجھیں اور اسے گائیڈ میں شامل کریں۔

آپ کو مائیگریشن گائیڈ کی کب ضرورت ہے؟

اگر آپ کی ریلیز میں صرف غیر توڑنے والی تبدیلیاں ہیں، تو آپ کو منتقلی کے رہنما کی ضرورت نہیں ہے۔ تبدیلی لاگ انٹری عام طور پر کافی ہوتی ہے۔ تاہم، اگر ریلیز میں ایک بھی بڑی تبدیلی ہوتی ہے، تو ڈویلپرز کو یہ جاننے کی ضرورت ہوتی ہے کہ ان کے کوڈ میں کیا اپ ڈیٹ کرنے کی ضرورت ہے۔ ہجرت کی رہنمائی اسی کے لیے ہے۔

انوینٹری API کے لیے منتقلی کی گائیڈ کیسے لکھیں۔

اب جب کہ آپ جان چکے ہیں کہ ہجرت کی ہدایت نامہ کیا ہے اور جب آپ کو اس کی ضرورت ہو تو اسے لکھنے کا وقت آگیا ہے۔ اس ٹیوٹوریل کے بقیہ حصے کے لیے، آپ پہلے ذکر کردہ انوینٹری API کے ساتھ کام کریں گے۔ ایک نمونہ API جو ڈویلپرز کو انوینٹری میں آئٹمز کی فہرست بنانے، انوینٹری کی سطحوں کو چیک کرنے اور انوینٹری کو شامل یا ہٹانے کی اجازت دیتا ہے۔

Inventory API v1 سے v2 میں منتقل ہو رہا ہے، اور v1 31 مارچ 2027 کو کام کرنا بند کر دے گا۔ میں نے GitHub ریپوزٹری میں دونوں ورژنز کے حوالے سے دستاویزات رکھ دی ہیں، اس لیے براہ کرم اسے پبلک کریں۔ v1-reference.md اور v2-reference.md پہلو بہ پہلو آپ پہلے مرحلے میں ان کا بہت زیادہ موازنہ کریں گے۔

مرحلہ 1: تمام تبدیلیوں کی فہرست اور درجہ بندی کریں۔

مضمون لکھنے سے پہلے، مجھے اس کی مکمل فہرست درکار ہے کہ دونوں ورژن کے درمیان کیا تبدیلی آئی ہے۔ یہاں چھوٹ جانے والی کسی بھی تبدیلی کو گائیڈ میں شامل نہیں کیا جائے گا، اور ڈویلپرز کو ان کے بارے میں تب ہی پتہ چلے گا جب ان کا کوڈ ناکام ہو جائے گا۔

سیکشن کے لحاظ سے دو حوالہ جاتی دستاویزات کے سیکشن کا موازنہ کرکے شروع کریں۔ مثال کے طور پر، یہاں ایک آئٹم کے ہر ورژن سے اسٹاک کی 5 یونٹس کو ہٹانے کی وہی درخواست ہے:

# v1
curl -X POST "https://api.example.com/v1/items/itm_204/adjust?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"qty": -5}'

# v2
curl -X POST "https://api.example.com/v2/items/itm_204/adjust" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": -5}'

یہ درخواست تین تبدیلیوں کو ظاہر کرتی ہے:

  • پہلے سے طے شدہ URL کو یہاں سے منتقل کر دیا گیا ہے: /v1 کو /v2.
  • API کلید کو URL سے اس میں منتقل کر دیا گیا ہے: Authorization ہیڈر
  • qty ~ بن گیا۔ quantity.

اس طرح کی دونوں دستاویزات کا جائزہ لیں اور جو بھی فرق آپ محسوس کرتے ہیں اسے لکھیں، چاہے وہ کتنا ہی چھوٹا ہو۔

جسمانی مصنوعات کے لیے، مکمل طور پر دستاویزات پر انحصار نہ کریں۔ اس کی وجہ یہ ہے کہ دستاویزات پرانی ہو سکتی ہیں۔ تبدیلی لاگ اور پل کی درخواستوں کو بھی چیک کریں، اور نیا ورژن بنانے والے انجینئر سے لسٹ چیک کرنے کو کہیں۔ اگر دونوں ورژن میں OpenAPI کی تفصیلات ہیں، تو آپ دو ورژنز کا موازنہ کرنے اور بڑی تبدیلیاں دکھانے کے لیے oasdiff جیسے ٹول کا استعمال کر سکتے ہیں۔

ایک بار جب آپ کے پاس اپنی فہرست ہے، تو اسے میز پر رکھیں. ہر تبدیلی کے لیے، ریکارڈ کریں کہ یہ کہاں ہوا، آیا یہ ٹوٹ گیا، اور کون متاثر ہوا۔

# تبدیلی کہاں تباہی؟ یہ کس کو متاثر کرتا ہے۔
1 پہلے سے طے شدہ URL اس سے بدل گیا ہے: /v1 کو /v2 تمام اختتامی نکات ہاں ہر کوئی
2 API کلید استفسار کے پیرامیٹر میں ہے۔ Authorization ہیڈر تمام اختتامی نکات ہاں ہر کوئی
3 page اور per_page کے ساتھ تبدیل کر دیا limit اور cursor GET /items ہاں اشیاء کی فہرست سازی کرنے والا شخص
4 qty نام بدل کر رکھ دیا گیا۔ quantity جواب میں GET /items, GET /items/{id} ہاں وہ شخص جو اسٹاک لیول پڑھتا ہے۔
5 qty نام بدل کر رکھ دیا گیا۔ quantity درخواست کے جسم میں POST /items/{id}/adjust ہاں وہ شخص جو انوینٹری کو جوڑتا یا ہٹاتا ہے۔
6 غلطی کے جواب کو سٹرنگ سے ایک آبجیکٹ میں تبدیل کر دیا گیا ہے جس پر مشتمل ہے: code اور message تمام اختتامی نکات ہاں جو غلطیوں کو سنبھالتا ہے۔
7 نیا 429 بہت زیادہ درخواستیں بھیجنے میں خرابی۔ تمام اختتامی نکات ‘ہاں’ کے طور پر علاج کریں وہ لوگ جو بہت زیادہ درخواستیں بھیجتے ہیں۔
8 نیا warehouse_id آئٹم کے جواب میں فیلڈز GET /items, GET /items/{id} نہیں کوئی بھی جو جاننا چاہتا ہے کہ اسٹاک کہاں ہے۔
9 نئے اختیارات reason درخواست کے جسم میں فیلڈز POST /items/{id}/adjust نہیں کوئی بھی جو ریکارڈ کرنا چاہتا ہے کہ اسٹاک کیوں تبدیل ہوئے۔

نوٹ کرنے کی چیزیں qty نام بدلنا دو بار ظاہر ہوتا ہے: ایک بار جواب میں اور ایک بار درخواست کے باڈی میں۔ نام کی تبدیلی ایک جیسی ہے، لیکن ڈویلپر نے اسے کوڈ کے مختلف حصے میں تبدیل کیا ہے، اس لیے اسے دو الگ الگ تبدیلیوں کے طور پر درج کیا گیا ہے۔

تبدیلی 7 انٹرمیڈیٹ کیس کی ایک مثال ہے جس کا پہلے ذکر کیا گیا ہے۔ کوئی راستہ نہیں 429 غلطی خود کسی چیز کو نہیں توڑتی ہے، لیکن کوڈ جو اسے ہینڈل نہیں کرتا ہے ان طریقوں سے ناکام ہوسکتا ہے جس کی ڈویلپر کو توقع نہیں تھی، لہذا ہم اسے ٹوٹا ہوا سمجھتے ہیں۔

تمام تبدیلیوں کو درج اور درجہ بندی کے ساتھ، اب آپ جانتے ہیں کہ گائیڈ کو کیا احاطہ کرنا چاہیے۔ نو میں سے سات تبدیلیوں کے لیے ڈویلپر کی کارروائی کی ضرورت ہوتی ہے، یہ گائیڈ کا ایک بڑا حصہ ہے۔

مرحلہ 2: گائیڈ کا خاکہ اور خلاصہ لکھیں۔

اگلا فیصلہ جو آپ کو کرنے کی ضرورت ہے وہ یہ ہے کہ اپنے گائیڈ کو کس طرح تشکیل دیا جائے۔ ڈویلپرز نقل مکانی کی گائیڈز کو کور سے کور تک نہیں پڑھتے ہیں جیسے کہ وہ آرٹیکلز ہیں۔ وہ ان عوامل کو تلاش کرتے ہیں جو ان پر اثر انداز ہوتے ہیں، انہیں ٹھیک کرتے ہیں، اور پھر آگے بڑھتے ہیں۔ لہذا، ساخت کو اسی ترتیب میں سوالات کا جواب دینا چاہئے جس میں ان سے پوچھا جاتا ہے.

یہاں وہ خاکہ ہے جسے ہم انوینٹری API ٹیوٹوریل کے لیے استعمال کرتے ہیں:

# Migrating from Inventory API v1 to v2

## Summary
## Timeline
## Breaking changes
### Base URL
### Authentication
### Pagination
### Field rename: qty to quantity
### Error responses
### Rate limiting
## New features
## Migration checklist
## Test your migration
## Roll back

خلاصہ اور ٹائم لائن پہلے ظاہر ہوتے ہیں کیونکہ وہ ان دو سوالوں کا جواب دیتے ہیں جو ہر ڈویلپر کسی بھی چیز سے پہلے پوچھتا ہے: "کیا یہ مجھ پر اثر انداز ہوگا؟” اور "میرے پاس کتنا وقت ہے؟”

بریکنگ تبدیلیاں اس کے بعد آتی ہیں کیونکہ انہیں کارروائی کی ضرورت ہوتی ہے، اور ان کے بعد نئی خصوصیات آتی ہیں کیونکہ ڈویلپرز انہیں نظر انداز کر سکتے ہیں اور کوڈ نہیں ٹوٹے گا۔ چیک لسٹ، ٹیسٹنگ، اور رول بیک سیکشنز آخری ہیں کیونکہ ڈویلپر کی جانب سے کوئی تبدیلی کرنے کے بعد ان کی ضرورت ہوتی ہے۔

خاکہ پر فیصلہ کرنے کے بعد، خلاصہ لکھیں۔ ڈویلپرز کو تبدیلیوں، کون متاثر ہوں گے، اور مقررہ تاریخ سے آگاہ کرنا یقینی بنائیں۔ اسے چند جملوں تک رکھیں۔

انوینٹری API کے لیے:

# Migrating from Inventory API v1 to v2

## Summary

Inventory API v2 changes how you authenticate, how you page through
items, and how errors come back. It also renames the `qty` field to
`quantity`. If your code calls any v1 endpoint, you need to update it
before **March 31, 2027**, when v1 stops working.

This guide walks you through each change with before-and-after code.

## Timeline

| Date | What happens |
|---|---|
| Now | v2 is available. v1 still works, so you can migrate at your own pace. |
| March 31, 2027 | v1 stops working. Requests to `/v1` endpoints will fail. |

ڈیڈ لائن پہلے پیراگراف میں بولڈ میں ظاہر ہوتی ہے۔ اگر ڈویلپر گائیڈ سے صرف ایک جملہ پڑھتے ہیں، تو یہ وہ جملہ ہونا چاہئے جس میں تاریخ شامل ہو۔

مرحلہ 3: کوڈ سے پہلے اور بعد میں ہر تبدیلی کو دستاویز کریں۔

یہ گائیڈ کا اہم حصہ ہے اور جہاں ڈویلپر اپنا زیادہ تر وقت صرف کرتے ہیں۔ ہر بڑی تبدیلی کے لیے، آپ جاننا چاہتے ہیں کہ آپ کے کوڈ میں کیا تبدیلی آئی ہے اور کس چیز کو اپ ڈیٹ کرنے کی ضرورت ہے۔

مستقل مزاجی کو برقرار رکھنے کے لیے، انہی چار حصوں کا استعمال کرتے ہوئے تمام تبدیلیوں کو دستاویز کریں۔

  1. کیا بدل گیا ہے
  2. یہ کیوں بدل گیا (صرف اس صورت میں جب وجہ ڈویلپر کے لیے مددگار ہو)
  3. کوڈ سے پہلے اور بعد میں
  4. آپ کو کیا کرنے کی ضرورت ہے

توثیق کی تبدیلیاں ایک اچھی مثال ہیں کیونکہ API کا استعمال کرنے والا ہر ڈویلپر ایسا کرے گا۔

### Authentication

**What changed:** v2 no longer accepts your API key as a query
parameter. Send it in the `Authorization` header instead.

**Why it changed:** API keys in URLs can end up in server logs and
browser history, where other people can see them. A header keeps
the key out of those places.

**Before (v1):**

```javascript
const res = await fetch(`${BASE_URL}/items?api_key=${API_KEY}`);
```

**After (v2):**

```javascript
const res = await fetch(`${BASE_URL}/items`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
```

**What you need to do:** Remove `api_key` from every request URL and
send the key in the `Authorization` header. v2 rejects keys sent as
query parameters.

"کیوں” حصہ صرف دو جملے لمبا ہے، لیکن یہ ایک اہم کردار ادا کرتا ہے۔ ڈویلپرز پہلے سے کام کرنے والے کوڈ کو تبدیل کرنا پسند نہیں کرتے ہیں، لہذا بہت سے لوگ ہجرت کے آخری لمحے تک انتظار کرتے ہیں۔ ایک بار جب آپ جان لیں کہ تبدیلیاں آپ کی API کلیدوں کو محفوظ رکھیں گی، تو انہیں ابھی لاگو کرنے کی واضح وجہ ہے۔

باقی تبدیلیاں

دیگر تبدیلیاں اسی طرز کی پیروی کرتی ہیں، لیکن تمام تبدیلیوں کو یکساں تفصیل کی ضرورت نہیں ہوتی۔ سادہ تبدیلیوں کے لیے صرف ایک بیان اور کوڈ کی ایک مختصر لائن کی ضرورت ہوتی ہے۔ تبدیلیاں جو ڈویلپرز کے اپنے کوڈ کو ترتیب دینے کے طریقے کو متاثر کرتی ہیں ان کے لیے پہلے اور بعد میں مکمل مثالوں کی ضرورت ہوتی ہے۔

انوینٹری API تبدیلیوں میں سے کچھ آسان ہیں، ہر ایک میں صرف ایک یا دو لائن کی ضرورت ہوتی ہے۔

  • بنیادی URL: تمام اختتامی نقطوں کو یہاں سے منتقل کر دیا گیا ہے: /v1 کو /v2. ڈویلپر بنیادی URLs کو ایک جگہ پر اپ ڈیٹ کرتے ہیں۔
  • qty نام بدل کر رکھ دیا گیا۔ quantity: ڈویلپرز جب بھی فیلڈز کو جواب میں پڑھتے ہیں اور ہر بار درخواست کے باڈی میں بھیجتے ہیں تو ان کا نام تبدیل کرتے ہیں۔
  • نئے فیلڈز: warehouse_id ردعمل اور reason ایڈجسٹمنٹ کی درخواست کا باڈی اختیاری اضافے پر مشتمل ہے۔ اسے چھوڑنے سے کوئی پریشانی نہیں ہوگی، اس لیے گائیڈ کے "نیا کیا ہے” سیکشن پر جائیں۔

صفحہ بندی اور غلطیاں مختلف ہیں۔ دونوں ڈویلپرز کے لوپ لکھنے اور غلطی سے نمٹنے کے طریقے کو تبدیل کرتے ہیں، اس لیے مکمل کوڈ کی مثالیں درکار ہیں۔

v1 نے صفحہ نمبرز کا استعمال کیا، لہذا ڈویلپرز نے اس وقت تک تکرار کی جب تک کہ وہ آخری صفحہ پر نہ پہنچ جائیں۔ v2 ایک کرسر استعمال کرتا ہے، لہذا یہ اگلے تک صفحات کی درخواست کرتا رہتا ہے۔ next_cursor یہ کچھ اس طرح لوٹاتا ہے: null:

// v1: page numbers
let page = 1;
let totalPages;

do {
  const res = await fetch(
    `${BASE_URL}/items?page=${page}&per_page=100&api_key=${API_KEY}`
  );
  const body = await res.json();
  saveItems(body.data);
  totalPages = body.total_pages;
  page++;
} while (page <= totalPages);

// v2: cursor
let cursor = null;

do {
  const query = cursor ? `limit=100&cursor=${cursor}` : "limit=100";
  const res = await fetch(`${BASE_URL}/items?${query}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const body = await res.json();
  saveItems(body.data);
  cursor = body.next_cursor;
} while (cursor);

خرابی اور شرح کو محدود کرنا

v1 میں error یہ ایک تار تھا۔ v2 میں code اور messageاور کچھ نیا ہے۔ 429 ایک خرابی پیش آ گئی۔ Retry-After یہ ایک ہیڈر ہے جو ڈویلپر کو تاخیر سے آگاہ کرتا ہے۔ دونوں تبدیلیاں غلطی سے نمٹنے پر اثر انداز ہوتی ہیں، اس لیے گائیڈ ان کا احاطہ کرتا ہے۔

// v1
if (!res.ok) {
  const body = await res.json();
  console.error(body.error); // "Item not found"
}

// v2
if (!res.ok) {
  const { error } = await res.json();

  if (error.code === "rate_limited") {
    const waitSeconds = Number(res.headers.get("Retry-After"));
    // Wait, then retry the request
  }

  console.error(error.message); // "Item not found"
}

اس میں فیز 1 کی فہرست سے تمام تبدیلیاں شامل ہیں۔ تیار شدہ گائیڈ میں، آپ کو ایک مکمل اہم تبدیلیوں کا سیکشن نظر آئے گا جس میں تمام تبدیلیاں مکمل ریکارڈ کی گئی ہیں۔

مرحلہ 4: مائیگریشن چیک لسٹ شامل کریں۔

چیک لسٹ ہر ہجرت گائیڈ کا معیاری حصہ نہیں ہیں، اور بہت سے اچھے گائیڈز کے پاس یہ نہیں ہیں۔ لیکن زیادہ تر معاملات میں، میں اس خصوصیت کو شامل کرنے کو ترجیح دیتا ہوں۔ اس کی وجہ یہ ہے کہ اس سے ڈویلپرز کو اس بات پر نظر رکھنے میں مدد ملتی ہے کہ انہوں نے کیا اپ ڈیٹ کیا ہے اور کیا بچا ہے۔ تبدیلیوں کو پڑھنے کے بعد، آپ چیک لسٹ کا استعمال ہر اس چیز کو چیک کرنے کے لیے کر سکتے ہیں جس کو اپ ڈیٹ کرنے کی ضرورت ہے، لہذا آپ کو اپنی کھوئی ہوئی چیز کو تلاش کرنے کے لیے دوبارہ گائیڈ کے ذریعے اسکرول کرنے کی ضرورت نہیں ہے۔

انوینٹری API گائیڈ سے چیک لسٹ یہ ہے:

## Migration checklist

- [ ] Change the base URL from `/v1` to `/v2`
- [ ] Move the API key from the `api_key` query parameter to the `Authorization: Bearer` header
- [ ] Replace `page` and `per_page` with `limit` and `cursor`
- [ ] Remove code that reads `total_pages`
- [ ] Rename `qty` to `quantity` in code that reads responses
- [ ] Rename `qty` to `quantity` in adjust request bodies
- [ ] Read `error.message` and `error.code` instead of `error`
- [ ] Handle `429` errors using the `Retry-After` header
- [ ] Test your migration (see below)

کہ - [ ] نحو ہر آئٹم کو ایک چیک باکس کے طور پر نشان زد کرتا ہے، لیکن جب میں دستاویز کی سائٹ پر باکس کو چیک کرتا ہوں تو یہ اسے محفوظ نہیں کرتا ہے۔ لہذا، ڈویلپر اس فہرست کو بطور حوالہ استعمال کر سکتے ہیں۔

اپنی چیک لسٹ بناتے وقت، درج ذیل کو ذہن میں رکھیں:

  • فی آئٹم ایک کارروائی: ہر آئٹم ایسی چیز ہے جسے ڈویلپر انجام دے سکتے ہیں اور جانچ سکتے ہیں۔ "اپ ڈیٹ صفحہ بندی" بہت مبہم ہے، لہذا یہ پیرامیٹر کی تبدیلی کا مجموعہ ہے اور total_pages پاس ورڈ
  • ایک ہی ترتیب جیسا کہ گائیڈ میں ہے: آئٹمز بریکنگ چینجز سیکشن کی ترتیب کی پیروی کرتے ہیں، لہذا اگر ڈیولپرز کو مسائل کا سامنا کرنا پڑتا ہے تو وہ صحیح سیکشن پر واپس آ سکتے ہیں۔
  • صرف اہم تبدیلیاں: نیا warehouse_id اور reason فیلڈ فہرست میں نہیں ہے۔ کیونکہ ڈویلپرز کو اس کے بارے میں کچھ کرنے کی ضرورت نہیں ہے۔
  • ٹیسٹ آخری آتا ہے: آخری آئٹم ڈیولپرز کو ٹیسٹنگ سیکشن کے بارے میں بتاتا ہے تاکہ وہ اس بات کو یقینی بنانے سے پہلے کہ سب کچھ کام کر رہا ہے v2 پر سوئچ نہ کریں۔

اگر آپ کی منتقلی میں صرف 1 یا 2 تبدیلیاں ہیں، تو آپ چیک لسٹ کو چھوڑ سکتے ہیں کیونکہ گائیڈ دہرائی جاتی ہے۔

مرحلہ 5: ٹیسٹ اور رول بیک ہدایات شامل کریں۔

ڈویلپرز اس بات کو یقینی بنانا چاہیں گے کہ پروڈکشن ماحول میں v2 پر سوئچ کرنے سے پہلے ان کا نیا کوڈ کام کرے۔ اور اگر منتقلی کے بعد کچھ غلط ہو جاتا ہے، تو آپ کو واپس جانے کا راستہ درکار ہوگا۔ یہ مرحلہ دونوں کا احاطہ کرتا ہے۔

ڈویلپرز کو منتقلی کی جانچ میں مدد کریں۔

ٹیسٹنگ سیکشن کو ڈویلپرز کو بتانا چاہیے کہ ان کے کوڈ کے کون سے حصے ٹوٹنے کا زیادہ امکان ہے۔ انوینٹری API کے لیے، صفحہ بندی، غلطیاں، اور شرح کی حدیں ہیں۔ اس کی وجہ یہ ہے کہ ڈویلپر نہ صرف URLs یا فیلڈ کے نام بدلتے ہیں بلکہ یہ بھی کہ وہ اپنی منطق کیسے لکھتے ہیں۔

v1 اور v2 دونوں ایک آخری تاریخ تک کام کرتے ہیں، لہذا ڈویلپر دونوں ورژنز پر ایک ہی درخواست چلا سکتے ہیں اور نتائج کا موازنہ کر سکتے ہیں۔ وہ جو کھو رہے ہیں اسے پکڑنے کا یہ سب سے آسان طریقہ ہے۔

یہ انوینٹری API گائیڈ کا ٹیسٹنگ سیکشن ہے۔

## Test your migration

Before you switch your production code to v2, check that it behaves the same way it did on v1:

1. **Compare the full item list.** Page through all items in v1 and v2 and check that you get the same number of items with the same quantities.
2. **Test the last page.** Make sure your loop stops when `next_cursor` is `null` and doesn't request an extra page.
3. **Test an error.** Request an item ID that doesn't exist and check that your code reads `error.code` (`item_not_found`) and `error.message` correctly.
4. **Test a stock adjustment.** Add or remove stock on a test item with `quantity`, then fetch the item and check that the new value is correct.
5. **Test rate limiting.** If you send requests in bulk, make sure your code waits and retries when it gets a `429`.

ہر ٹیسٹ ایک تبدیلی پر توجہ مرکوز کرتا ہے اور دکھاتا ہے کہ صحیح نتیجہ کیسا ہوگا۔ "ٹیسٹ صفحہ بندی" جیسے مبہم اقدامات زیادہ مددگار نہیں ہیں کیونکہ ڈویلپرز نہیں جانتے کہ کیا تلاش کرنا ہے۔

ڈویلپرز کو رول بیک کرنے کا طریقہ سکھائیں۔

یہاں تک کہ اچھی جانچ کے باوجود، ڈویلپرز کی منتقلی کے بعد مسائل پیدا ہو سکتے ہیں۔ رول بیک سیکشن آپ کو بتاتا ہے کہ اگر ایسا ہوتا ہے تو کیا کرنا ہے۔

انوینٹری API کے لیے، v1 31 مارچ 2027 تک کام کرتا رہے گا، رول بیکس کی اجازت دیتا ہے۔ گائیڈ ڈویلپرز سے کہتی ہے کہ وہ v1 کوڈ اس وقت تک رکھیں جب تک کہ وہ v2 کے بارے میں پراعتماد نہ ہوں اور ورژنز کے درمیان سوئچ کرنے کے لیے سیٹنگز استعمال کریں، اس لیے واپس جانے کا مطلب کوڈ کو دوبارہ لکھنا نہیں ہے۔

## Roll back

v1 keeps working until **March 31, 2027**, so you can switch back if something goes wrong after you migrate.

To make rolling back easy, keep your v1 code until you're confident v2 works, and switch between them with a setting, such as an environment variable, instead of editing code. After March 31, 2027, rolling back isn't possible, so finish testing well before that date.

آخری جملہ مت بھولنا۔ ڈیولپرز کو یہ جاننے کی ضرورت ہے کہ وہ اب v1 پر کب واپس نہیں جا سکتے، اس لیے ان کے پاس آخری تاریخ سے پہلے ٹیسٹ کرنے کے لیے کافی وقت ہے۔

مرحلہ 6: گائیڈ شائع اور اعلان کریں۔

گائیڈ مکمل ہونے کے بعد، اسے دستاویزات میں پوسٹ کریں اور ڈویلپرز کو بتائیں کہ گائیڈ دستیاب ہے۔ ان سے یہ توقع نہ کریں کہ وہ اسے خود ہی تلاش کر لیں گے۔

انوینٹری API کے لیے، میں اسے یہاں شیئر کروں گا:

  • دستاویز: v1 حوالہ جات والے صفحہ پر ایک بینر شامل کریں جو گائیڈ سے لنک کرتا ہے۔
  • تاریخ کو تبدیل کریں: گائیڈ سے منسلک ایک v2 اندراج شامل کریں۔
  • ای میل: میں اسے ڈیولپرز کو بھیجنے کے لیے v1 کا استعمال کرتا ہوں اور پھر انہیں آخری تاریخ سے پہلے ایک یا دو نوٹیفکیشن بھیجتا ہوں۔

آپ انجینئرنگ ٹیم میں شامل ہونے کی درخواست بھی کر سکتے ہیں۔ Sunset v1 جواب کے ہیڈر۔ ہم ہر جواب پر ایک اختتامی تاریخ دکھائیں گے، اس لیے جو ڈیولپرز ای میل سے محروم ہیں وہ اب بھی اسے دیکھ سکتے ہیں۔

گائیڈ کے شائع ہونے کے بعد اسے اپ ٹو ڈیٹ رکھنا یقینی بنائیں۔ اگر کوئی ڈویلپر ایک سپورٹ ٹکٹ میں یہی سوال پوچھتا ہے، تو گائیڈ میں جواب شامل کریں، اور v1 ختم ہونے کے بعد اسے پرانے کے طور پر لیبل کریں تاکہ نئے ڈویلپر غلطی سے اس کی پیروی نہ کریں۔

API مائیگریشن گائیڈز میں کی جانے والی سب سے عام غلطیاں کون سی ہیں؟

اگر ایک ڈویلپر نے مائیگریشن گائیڈ پڑھنا مکمل کر لیا ہے اور پھر بھی نہیں جانتا ہے کہ اپنے کوڈ میں کیا تبدیلی لانا ہے تو مائیگریشن گائیڈ ناکام ہو جائے گا۔ یہاں پانچ عام غلطیاں ہیں جو اس کا باعث بنتی ہیں اور ان سے کیسے بچنا ہے۔

  • اس کی وضاحت کرنے کے بجائے، تبدیلی لاگ سے لنک کریں: اگر آپ کچھ ایسا لکھتے ہیں کہ "براہ کرم مزید تفصیلات کے لیے تبدیلی کے لاگ سے رجوع کریں"، تو ڈویلپرز کو یہ سمجھنے کی ضرورت ہوگی کہ ان کے کوڈ کے لیے ہر تبدیلی کا کیا مطلب ہے۔ خود گائیڈ میں کسی بڑی تبدیلی کی وضاحت کریں۔
  • کوڈ کی مثال کو چھوڑنا: الفاظ میں تبدیلی کو بیان کرنا کافی نہیں ہے۔ v1 اور v2 کوڈ ساتھ ساتھ دکھائیں تاکہ ڈویلپر دیکھ سکیں کہ کیا اپ ڈیٹس کیے جا رہے ہیں۔
  • مقررہ تاریخیں چھپائیں: اگر اختتامی تاریخ کو گائیڈ کے بیچ میں دفن کر دیا جائے تو کچھ ڈویلپرز اس سے محروم ہو جائیں گے۔ اسے پہلے پیراگراف میں رکھیں۔
  • توڑنے اور نہ ٹوٹنے والی تبدیلیوں کا مرکب: جب بریکنگ تبدیلیوں کے ساتھ نئی اختیاری خصوصیات درج کی جاتی ہیں، تو ڈویلپرز کے لیے یہ فرق کرنا مشکل ہو جاتا ہے کہ کیا ضروری ہے اور کیا اختیاری ہے۔ انہیں الگ سیکشن میں رکھیں۔
  • ٹیسٹ ہدایات کو چھوڑیں: اس کے بغیر، ڈویلپرز پروڈکشن میں نئے ورژن پر سوئچ کرنے کے بعد مسائل دریافت کریں گے۔ براہ کرم مجھے بتائیں کہ آپ کیا ٹیسٹ کر رہے ہیں اور صحیح نتائج کیا ہیں۔

نتیجہ

اس ٹیوٹوریل میں، ہم نے انوینٹری API کے لیے شروع سے آخر تک ایک منتقلی گائیڈ بنایا ہے۔ ہم نے v1 اور v2 کے درمیان تمام تبدیلیاں درج کیں، ان سوالوں کے لیے ایک گائیڈ بنایا جو ڈویلپرز پوچھیں گے، ہر تبدیلی کو پہلے اور بعد کے کوڈ کے ساتھ دستاویز کیا، اور چیک لسٹ، ٹیسٹنگ کے مراحل، اور رول بیک پلان شامل کیا۔

آپ اسی عمل کو کسی بھی API کے لیے استعمال کر سکتے ہیں جس کے ساتھ آپ کام کرتے ہیں۔ اگر آپ کام کرنے کے لیے کچھ تلاش کر رہے ہیں، تو میرے پاس GitHub اور میرے بلاگ پر ایک مکمل انوینٹری API گائیڈ اور حوالہ دستاویزات موجود ہیں۔ ڈھانچے کو کاپی کریں اور کوئی تبدیلی کریں۔

اگر آپ کو یہ کارآمد لگا، تو ہم LinkedIn اور X پر تکنیکی تحریر اور دستاویزات کے بارے میں تجاویز کا اشتراک کرتے ہیں۔ بلا جھجھک رابطہ کریں۔

Scroll to Top