ہوٹل دستیابی API: سست سپلائرز کے لیے کلائنٹ ڈیزائن

کام کی درخواست عموماً بالکل بےضرر شکل میں آتی ہے: "بکنگ پیج پر ہوٹل سرچ لگا دو — سپلائر نے ہوٹل دستیابی API دے دیا ہے، sandbox بھی موجود ہے، ایک اسپرنٹ کا کام ہے۔" آپ دستاویزات پڑھتے ہیں، دبئی میں دو بالغ افراد کے لیے تین راتوں کی درخواست بھیجتے ہیں، اور جواب آ جاتا ہے۔ پھر یہی درخواست کسی ایسے شہر کے لیے بھیجتے ہیں جہاں ہوٹل زیادہ ہیں، اور کافی دیر تک کچھ واپس نہیں آتا — ایسی دیر جو بےچین کر دے۔ جب جواب آتا ہے تو اتنا بڑا ہوتا ہے کہ آپ کا JSON parser بھی اپنی زندگی کے فیصلوں پر نظرِ ثانی کرنے لگے۔
یہیں سے کام کی نوعیت بدل جاتی ہے۔ ہوٹل کی دستیابی کوئی سادہ lookup نہیں؛ یہ fan-out ہے۔ آپ کے صارف کا ایک سوال کئی سپلائرز سے کئی سوالوں میں بدل جاتا ہے، اور ہر سپلائر اپنی رفتار سے، اپنی اصطلاحات میں اور "کمرے" کے اپنے تصور کے ساتھ جواب دیتا ہے۔ جو کلائنٹ آپ بنائیں، اسے اس وقت بھی کارآمد رہنا ہے جب یہ fan-out ابھی مکمل نہ ہوا ہو۔ یہ تحریر اسی کلائنٹ کے ڈیزائن کے بارے میں ہے — ایسے developer کے لیے جو REST اور JSON اچھی طرح جانتا ہے، مگر جسے کبھی کسی ہوٹل کو یہ سمجھانا نہیں پڑا کہ مہمان کا non-refundable ریٹ مفت منسوخی کے ساتھ کیوں دکھایا گیا۔
ہوٹل دستیابی API آپ کے عام endpoints سے سست کیوں ہوتا ہے
باہر سے دیکھیں تو فلائٹ سرچ اور ہوٹل سرچ ایک جیسی لگتی ہیں: ایک query جاتی ہے، قیمتوں والے آپشن واپس آتے ہیں۔ اندر سے یہ دو الگ مسئلے ہیں۔ اگر آپ نے فلائٹ بکنگ API کے انضمام میں اصل میں کیا کچھ شامل ہوتا ہے پر ہمارے نوٹس پڑھے ہیں تو آپ جانتے ہیں کہ سرچ میں نظر آنے والی قیمت ہمیشہ وہی نہیں ہوتی جس پر بکنگ ہوتی ہے۔ ہوٹل اس کے اوپر ایک اور مشکل کا اضافہ کرتے ہیں: حجم۔
ایک شہر میں سیکڑوں پراپرٹیز ہو سکتی ہیں۔ ہر پراپرٹی کئی قسم کے کمرے بیچتی ہے۔ ہر قسم کا کمرہ کئی rate plans کے تحت بکتا ہے — ناشتے کے ساتھ، ناشتے کے بغیر، refundable، non-refundable، ممبر ریٹ، پیکج ریٹ۔ اور ہر rate plan ایک سے زیادہ سپلائر سے آ سکتا ہے: کوئی bedbank، کوئی channel manager، براہِ راست معاہدہ، یا وہ wholesaler جس سے آپ نے صرف اس لیے معاہدہ کیا کہ ایک خاص ہوٹل میں اس کا allotment باقی سب سے بہتر تھا۔ ان سب کو آپس میں ضرب دیں تو ایک "سادہ" سرچ ایک بڑا درخت بن جاتی ہے، جسے کئی ایسے ذرائع سے جوڑا گیا ہے جو ناموں اور IDs پر آپس میں متفق ہی نہیں۔
اس لیے سست حصہ شاذ ہی آپ کا کوڈ ہوتا ہے۔ سست حصہ وہ سب سے سست سپلائر ہے جس کا انتظار کرنے کا فیصلہ آپ نے خود کیا۔
بتدریج نتائج یا مکمل جواب: سوچ سمجھ کر انتخاب کریں
ہوٹل سرچ کے نتائج لوٹانے کے دو دیانت دار طریقے ہیں، اور زیادہ تر integrations آخرکار ان دونوں کے بیچ کسی ناخوشگوار جگہ پر جا ٹھہرتی ہیں۔
سب کا انتظار کریں۔ آپ کا backend تمام سپلائرز کو درخواست بھیجتا ہے، ہر ایک کے جواب یا timeout کا انتظار کرتا ہے، پھر نتائج کو یکجا کرتا ہے، دہرے نتائج ہٹاتا ہے، ترتیب دیتا ہے اور ایک مکمل فہرست لوٹاتا ہے۔ نتیجہ صاف ستھرا ہے: ایک درخواست، ایک جواب، اور ایسی قیمتیں جن کا موازنہ ممکن ہے کیونکہ سب ایک ساتھ سامنے ہیں۔ اس کی قیمت یہ ہے کہ آپ کا صارف ہر بار اتنی دیر spinner کو گھورتا رہتا ہے جتنی دیر آپ کا سب سے سست سپلائر لگاتا ہے۔
جو ملا ہے وہ بھیجتے جائیں۔ backend یہ fan-out شروع کرتا ہے اور فوراً ایک search handle لوٹا دیتا ہے۔ کلائنٹ اس handle کو poll کرتا ہے یا ایک stream کھلی رکھتا ہے، اور جیسے جیسے سپلائرز جواب دیتے ہیں، نتائج کھیپوں میں وصول کرتا ہے۔ پہلے ہوٹل جلد نظر آ جاتے ہیں۔ اس کی قیمت باقی ہر جگہ پیچیدگی کی صورت میں ادا ہوتی ہے: صارف فہرست پڑھ رہا ہوتا ہے اور اس کی ترتیب بدل جاتی ہے، "سب سے سستا" کا بیج اپنی جگہ سے ہٹ سکتا ہے، اور جو ہوٹل ایک سپلائر سے آیا تھا اسے بعد میں دوسرے سپلائر سے سستا ریٹ مل سکتا ہے۔
اگر آپ کا انٹرفیس کسی انسان کے سامنے کھلا سرچ پیج ہے تو بتدریج نتائج تقریباً ہمیشہ درست انتخاب ہیں۔ وہ شخص براؤز کر رہا ہے، کوئی batch job نہیں چلا رہا، اور جو صفحہ واضح طور پر کام کرتا دکھائی دے وہ خاموشی سے سوچتے ہوئے صفحے سے بہتر ہے۔ اگر آپ کا صارف کوئی دوسری مشین ہے — ریٹس کا موازنہ کرنے والا کوئی job، یا کوئی کارپوریٹ بکنگ ٹول جسے ایک حتمی جواب چاہیے — تو انتظار کرنا اکثر زیادہ سادہ بھی ہے اور درست بھی۔
جو بھی راستہ چنیں، تین اصول بتدریج کلائنٹ کو قابو میں رکھتے ہیں:
- ہر کھیپ کے ساتھ پوری سرچ کی تکمیل کی حالت آتی ہے، تاکہ کلائنٹ "ابھی مزید نتائج نہیں" اور "اب کبھی مزید نتائج نہیں آئیں گے" میں فرق کر سکے۔
- نتائج سرور پر ایک مستحکم ہوٹل key کے ذریعے یکجا کیے جاتے ہیں، محض فہرست کے آخر میں نہیں جوڑے جاتے۔ کلائنٹ کو کبھی خود یہ اندازہ نہیں لگانا چاہیے کہ دو کارڈ ایک ہی عمارت کے ہیں۔
- قیمت کے لحاظ سے ترتیب سرچ مکمل ہونے تک عارضی ہے، اور انٹرفیس یہ بات صاف بتاتا ہے۔ صارف اس فہرست کو معاف کر دیتے ہیں جو آہستہ آہستہ ٹھہر جائے؛ "سب سے کم قیمت" کے اس لیبل کو معاف نہیں کرتے جو بعد میں غلط نکلے۔
کمروں اور rate plans کی ماڈلنگ، تاکہ سب کچھ گڈمڈ نہ ہو
یہی وہ جگہ ہے جہاں زیادہ تر ہوٹل integrations خاموشی سے ناکام ہوتی ہیں، اور یہ ناکامی مہینوں بعد bug report کی بجائے support ticket کی شکل میں سامنے آتی ہے۔
سب سے پرکشش ماڈل سپاٹ ہوتا ہے: ہوٹل کے پاس آفرز کی ایک فہرست ہے، اور ہر آفر میں کمرے کا نام اور قیمت۔ اسکرین پر یہ اچھا لگتا ہے۔ پھر ایک سپلائر بظاہر ایک ہی کمرے کے لیے "Deluxe King" اور "Deluxe Room, 1 King Bed" بھیجتا ہے، دوسرا سپلائر دو واقعی مختلف کمروں کو ایک ہی نام دے دیتا ہے (ایک میں شہر کا منظر ہے، دوسرے میں نہیں)، اور تیسرا ایسا ریٹ بھیجتا ہے جس کی قیمت فی رات ہے جبکہ باقی سب کی قیمت پورے قیام کی۔ سپاٹ فہرست آپ کو نہیں بتا سکتی کہ آپ ان میں سے کس صورت کو دیکھ رہے ہیں۔ وہ بس انہیں دکھا دیتی ہے۔
جو ماڈل حقیقی سپلائرز کا سامنا کر کے بھی قائم رہے، اس میں کم از کم چار سطحیں ہوتی ہیں، اور وہ انہیں ایک دوسرے سے الگ رکھتا ہے:
| سطح | اس میں کیا ہوتا ہے | کس غلطی سے بچنا ہے |
|---|---|---|
| ہوٹل | آپ کی اپنی مستحکم ID، جو ہر سپلائر کے کوڈ سے میپ ہو | کسی سپلائر کی ہوٹل ID کو اپنی primary key بنا لینا |
| کمرہ | گنجائش (occupancy)، بستروں کی ترتیب، اور سپلائر کا اپنا متن جوں کا توں | کمروں کے نام اتنے "صاف" کرنا کہ دو مختلف کمرے ایک ہو جائیں |
| Rate plan | کھانے کی بنیاد (board basis)، رقم واپسی کی شرط، ادائیگی کی قسم، اور یہ کہ کس سپلائر سے آیا | ناشتے یا رقم واپسی کو کمرے کے نام کا حصہ سمجھنا |
| قیمت | پورے قیام کی کل رقم، کرنسی، کون سے ٹیکس اور فیس اس میں شامل ہیں اور کون سے ہوٹل پر ادا ہوں گے | فی رات کی رقم کو پورے قیام کی رقموں کے برابر دکھانا، یا آمد پر ادا ہونے والی فیس چھپانا |
آپ اس سے اختلاف کر سکتے ہیں کہ لکیریں کہاں کھینچی جائیں — کچھ ٹیمیں occupancy کو الگ سطح بنا دیتی ہیں، اور جب آپ ایک ہی بکنگ میں کئی کمرے بیچنے لگیں تو یہ معقول بات ہے۔ جو آپ نہیں کر سکتے وہ یہ ہے کہ سطحوں کو صرف اس لیے ملا دیں کہ انٹرفیس ان میں سے دو ہی دکھاتا ہے۔ انٹرفیس رینڈر کے وقت سب کچھ سپاٹ کر سکتا ہے۔ ڈیٹا کو ایسا نہیں ہونا چاہیے۔
ایک بات الگ سے کہنے کے لائق ہے: آپ جو کچھ بھی normalise کریں، اس کے ساتھ سپلائر کی بھیجی ہوئی کمرے کی اصل تفصیل بھی محفوظ رکھیں۔ جب مہمان پہنچے اور اسے واؤچر والے کمرے کی بجائے کوئی اور کمرہ ملے تو سب سے پہلا سوال یہی ہوگا کہ سپلائر نے اصل میں بھیجا کیا تھا۔
منسوخی کی پالیسی ڈیٹا ہے، کوئی پیراگراف نہیں
بہت سے سپلائرز منسوخی کی شرائط سادہ متن میں بھیجتے ہیں: "آمد سے 3 دن پہلے تک مفت منسوخی، اس کے بعد 1 رات کا جرمانہ۔" بڑا دل چاہتا ہے کہ یہی جملہ دکھا کر آگے بڑھ جائیں۔
ایسا نہ کریں۔ متن کا نہ موازنہ ہو سکتا ہے، نہ اسے ترتیب دیا جا سکتا ہے، نہ فلٹر کیا جا سکتا ہے، نہ اس پر عمل کروایا جا سکتا ہے۔ آپ کا صارف صرف refundable ریٹس دیکھنا چاہتا ہے۔ آپ کی فنانس ٹیم جاننا چاہتی ہے کہ کون سی بکنگز کل non-refundable ہو جائیں گی، تاکہ ایجنسی ڈیڈ لائن گزرنے سے پہلے کلائنٹ سے رابطہ کر لے۔ بکنگ کے بعد والے flow کو گاہک کو اسی لمحے، جب وہ cancel دبائے، ٹھیک ٹھیک بتانا ہے کہ اس سے کتنی رقم کٹے گی۔ ان میں سے کچھ بھی ایک جملے کے سہارے نہیں چل سکتا۔
ہر پالیسی کو جرمانے کی کھڑکیوں (penalty windows) کی ایک ترتیب وار فہرست کے طور پر ماڈل کریں: اس لمحے سے اُس لمحے تک جرمانہ اتنی رقم ہے (یا قیام کا اتنا حصہ، یا اتنی راتیں)۔ حدیں timezone کے ساتھ timestamps ہوں — ہوٹل کا timezone، نہ آپ کے سرور کا اور نہ صارف کا — کیونکہ "آمد سے 3 دن پہلے" کا لمحہ اس پر منحصر ہے کہ آپ کس کی آدھی رات سے گن رہے ہیں۔ سپلائر کا اصل متن ساختہ ورژن کے ساتھ محفوظ رکھیں، دکھائیں ساختہ ورژن، اور اگر دونوں میں تضاد ہو تو اسے چھپانے کی بجائے تحقیق کا معاملہ سمجھیں۔
اور پالیسی کو صرف سرچ کے وقت نہیں، بکنگ کے وقت بھی دوبارہ چیک کریں۔ ان دو کالز کے بیچ پالیسیاں اس سے کہیں زیادہ بار بدلتی ہیں جتنا کوئی توقع کرتا ہے۔
غلطی کی اصل قیمت کیا ہے
سست سرچ کی قیمت کھوئی ہوئی conversions ہیں — بری بات ہے مگر نظر آتی ہے؛ کوئی نہ کوئی شکایت ضرور کرے گا۔ مہنگی ناکامیاں وہ ہیں جو خاموش رہتی ہیں۔
جو ریٹ refundable دکھایا گیا مگر سپلائر کے نزدیک non-refundable ہے، وہ ایسے گاہک سے تنازع ہے جس کے پاس اسکرین شاٹ موجود ہے، اور جرمانہ عموماً ایجنسی خود بھرتی ہے۔ فی رات کی قیمت کو پورے قیام کی کل رقم بنا کر دکھایا جائے تو کمرے لاگت سے کم پر بکتے رہتے ہیں، جب تک اکاؤنٹس میں کوئی اسے پکڑ نہ لے۔ ایک کمرہ کسی دوسرے کمرے میں ضم ہو جائے تو چار افراد کا خاندان دو افراد کے لیے بنے کمرے میں جا پہنچتا ہے۔ ہوٹل پر ادا ہونے والی وہ فیسیں جو کبھی دکھائی ہی نہیں گئیں، فائیو اسٹار ریویو کو chargeback میں بدل دیتی ہیں۔ ان میں سے ہر ایک پہلے اسپرنٹ میں کیا گیا ماڈلنگ کا فیصلہ ہے، عموماً "بعد میں ٹھیک کر لیں گے" کے عنوان سے۔
کیشنگ: کیا رکھ سکتے ہیں اور کیا ہرگز نہیں
ہوٹل API جوڑنے والی ہر ٹیم آخرکار یہ پوچھتی ہے کہ کیا نتائج کو کیش کر کے سرچ کو تیز اور سستا بنایا جا سکتا ہے۔ جواب ہے: ہاں، کچھ چیزوں کے لیے — اور ان کے بیچ کی لکیر کسی بھی performance نمبر سے زیادہ اہم ہے۔
Static مواد — ہوٹلوں کے نام، پتے، coordinates، تصاویر، سہولتوں کی فہرستیں، کمروں کی تفصیل — کم ہی بدلتا ہے، اور یہی وہ چیز ہے جسے اپنے اسٹور میں کھل کر کیش کرنا چاہیے۔ سپلائر کی شرائط دیکھ لیں کہ آپ اسے کیسے محفوظ کر سکتے اور دکھا سکتے ہیں؛ کچھ لائسنس اس پر پابندیاں لگاتے ہیں۔ ہر سرچ پر اسے لائیو منگوانا بلا فائدہ سستی ہے۔
لائیو ریٹس اور دستیابی کا معاملہ الگ ہے۔ کیش کی گئی قیمت محض ایک اندازہ ہے کہ سپلائر کتنا چارج کرے گا، اور سپلائرز آپ کے اندازوں کے پابند نہیں۔ صفحہ دکھانے کے لیے سرچ نتائج کی مختصر مدت کی کیشنگ قابلِ قبول ہو سکتی ہے — بشرطیکہ بکنگ کا ہر راستہ پیسے لینے سے پہلے سپلائر سے دوبارہ قیمت لے، اور انٹرفیس بدلی ہوئی قیمت کو error نہیں بلکہ ایک معمول کا نتیجہ سمجھے۔ کچھ سپلائرز یہ حد بھی رکھتے ہیں کہ بکنگ کے مقابلے میں آپ کتنی بار سرچ کر سکتے ہیں؛ ایسی جارحانہ کیشنگ جو ان سے آپ کا اصل ٹریفک چھپا دے، کوئی ایسا چور دروازہ نہیں جس پر بھروسا کیا جائے۔
جو چیز کبھی کیش نہیں ہونی چاہیے وہ ہر وہ چیز ہے جو کسی وعدے کی نمائندگی کرے: hold کیا گیا price token، بکنگ ریفرنس، منسوخی کا کوٹ۔ یہ ایک صارف اور ایک لمحے کی ملکیت ہیں۔
کام مکمل کہنے سے پہلے
ایک مختصر جانچ، جو حقیقی بکنگز آنے سے پہلے اپنے integration پر چلا لینی چاہیے:
- سرچ تکمیل کی حالت لوٹاتی ہے، اور کلائنٹ اس سے پہلے اور بعد میں مختلف رویہ رکھتا ہے۔
- ہوٹلوں کی key آپ کی اپنی ID ہے، اور ہر سپلائر کا کوڈ اسی سے میپ ہے۔
- کمرہ، rate plan اور قیمت آپ کے ڈیٹا میں الگ الگ objects ہیں، اسکرین پر چاہے کچھ بھی دکھے۔
- ہر قیمت بتاتی ہے کہ وہ فی رات ہے یا پورے قیام کی، اور آمد پر کیا ادا کرنا ہوگا۔
- منسوخی کی پالیسیاں ہوٹل کے timezone میں وقت کے ساتھ بندھی جرمانے کی کھڑکیوں کی صورت میں محفوظ ہیں، اور اصل متن بھی ساتھ رکھا گیا ہے۔
- بکنگ کا راستہ کسی سے پیسے لینے سے پہلے دوبارہ قیمت لیتا اور پالیسی دوبارہ پڑھتا ہے۔
- جو چیز کسی وعدے کی نمائندگی کرتی ہے، وہ کبھی کیش سے نہیں دی جاتی۔
اگر آپ یہ سوچ رہے ہیں کہ یہ سب ہر سپلائر کے ساتھ الگ الگ بنائیں یا کسی ایسے پلیٹ فارم سے شروع کریں جو ان مسائل سے پہلے ہی گزر چکا ہے، تو معاہدے کا پہلو بھی کوڈ جتنا ہی اہم ہے — ہوٹل consolidator معاہدوں اور bedbank ریٹس پر ہماری تحریر بتاتی ہے کہ کیا مانگنا چاہیے۔ ہمارے اپنے فلائٹ اور ہوٹل APIs کسی self-serve key سے نہیں بلکہ بات چیت کے ذریعے کھولے جاتے ہیں؛ اگر آپ یہی راستہ دیکھنا چاہتے ہیں تو travel APIs کے صفحے پر یہ گفتگو شروع کریں۔
fan-out کبھی ختم نہیں ہوتا۔ اچھا کلائنٹ بس یہ دکھاوا کرنا چھوڑ دیتا ہے کہ وہ موجود نہیں۔