API موجودی هتل: طراحی برای تأمینکنندگان کُند

تیکت معمولاً بیآزار به نظر میرسد: «جستوجوی هتل را به صفحهی رزرو اضافه کن — تأمینکننده یک API موجودی هتل داده، sandbox هم دارد، یک اسپرینت کار است.» مستندات را میخوانید، برای دو بزرگسال، سه شب در دبی درخواست میفرستید و پاسخ برمیگردد. بعد همان درخواست را برای شهری با هتلهای بیشتر میفرستید و مدتی طولانی و ناخوشایند هیچ اتفاقی نمیافتد. وقتی بالاخره جواب میرسد، سندی است آنقدر بزرگ که پارسر JSON شما به انتخابهای زندگیاش شک میکند.
همان لحظه است که شکل کار عوض میشود. موجودی هتل یک lookup ساده نیست؛ یک fan-out است. یک سؤال از کاربر شما به سؤالهای متعدد از تأمینکنندگان متعدد تبدیل میشود و هرکدام با سرعت خودش، با واژگان خودش و با تعریف خودش از «اتاق» جواب میدهد. کلاینتی که میسازید باید در تمام مدتی که این fan-out هنوز در حال حل شدن است، به درد بخورد. این نوشته دربارهی طراحی همین کلاینت است — برای توسعهدهندهای که REST و JSON را خوب میشناسد و هنوز مجبور نشده به یک هتل توضیح دهد چرا نرخ غیرقابل استرداد مهمان، «کنسلی رایگان» نمایش داده شده است.
چرا API موجودی هتل از endpointهایی که میشناسید کُندتر است
جستوجوی پرواز و جستوجوی هتل از بیرون شبیه هماند: یک کوئری میرود و گزینههای قیمتدار برمیگردند. در زیر، مسئله یکی نیست. اگر یادداشت ما دربارهی آنچه اتصال به API رزرو پرواز واقعاً لازم دارد را خوانده باشید، میدانید قیمتی که جستوجو میکنید همیشه قیمتی نیست که رزرو میکنید. هتل یک دشواری دیگر هم روی آن میگذارد: حجم.
یک شهر میتواند صدها هتل داشته باشد. هر هتل چند نوع اتاق میفروشد. هر نوع اتاق زیر چند rate plan فروخته میشود — با صبحانه، بدون صبحانه، قابل استرداد، غیرقابل استرداد، نرخ اعضا، نرخ پکیج. و هر rate plan ممکن است از بیش از یک منبع بیاید: یک bedbank، یک channel manager، قرارداد مستقیم، یا عمدهفروشی که با او قرارداد بستید چون allotment او در یک هتل خاص از همه بهتر بود. اینها را در هم ضرب کنید و یک جستوجوی «ساده» درختی بزرگ است که از چند منبع سرهم شده و این منابع بر سر نامها و شناسهها توافقی ندارند.
پس بخش کُند بهندرت کد شماست. کُندترین تأمینکنندهای است که تصمیم گرفتید منتظرش بمانید.
نتایج تدریجی یا پاسخ کامل: آگاهانه انتخاب کنید
دو راه صادقانه برای برگرداندن نتایج جستوجوی هتل وجود دارد، و بیشتر اتصالها جایی ناخوشایند در میانهی این دو گیر میکنند.
منتظر همه بمانید. بکاند درخواست را پخش میکند، منتظر میماند تا هر تأمینکننده جواب بدهد یا timeout شود، ادغام میکند، تکراریها را حذف میکند، مرتب میکند و یک فهرست کامل برمیگرداند. نتیجه تمیز است: یک درخواست، یک پاسخ، و قیمتهایی که قابل مقایسهاند چون همه روی میزند. هزینهاش این است که کاربر هر بار به اندازهی کُندترین تأمینکننده به یک spinner خیره میماند.
هرچه دارید، بفرستید. بکاند fan-out را شروع میکند و بلافاصله یک search handle برمیگرداند. کلاینت آن handle را poll میکند یا یک stream باز نگه میدارد و نتایج را دستهدسته، همزمان با پاسخ تأمینکنندگان، دریافت میکند. اولین هتلها سریع ظاهر میشوند. هزینهاش پیچیدگی در همهجای دیگر است: فهرست در حالی که کاربر آن را میخواند جابهجا میشود، برچسب «ارزانترین» ممکن است جا عوض کند، و هتلی که از یک تأمینکننده آمده بعداً نرخ ارزانتری از تأمینکنندهی دیگر میگیرد.
اگر رابط شما یک صفحهی جستوجو در برابر یک انسان است، حالت تدریجی تقریباً همیشه درست است — آن آدم در حال گشتن است، نه اجرای یک batch، و صفحهای که پیداست دارد کار میکند از صفحهای که بیصدا فکر میکند بهتر است. اگر مصرفکنندهی شما یک ماشین دیگر است — یک job مقایسهی نرخ، یا ابزار رزرو سازمانی که یک پاسخ قطعی میخواهد — صبر کردن اغلب سادهتر و درست است.
هرکدام را که انتخاب کنید، سه قاعده کلاینت تدریجی را سالم نگه میدارد:
- هر دسته یک وضعیت تکمیل برای کل جستوجو دارد، تا کلاینت فرق «فعلاً نتیجهی دیگری نیست» و «دیگر هیچ نتیجهای نمیآید» را بداند.
- نتایج روی سرور با یک کلید پایدار هتل ادغام میشوند، نه اینکه پشت هم اضافه شوند. کلاینت هرگز نباید خودش کشف کند که دو کارت، یک ساختماناند.
- مرتبسازی بر اساس قیمت تا پایان جستوجو موقت است و رابط کاربری همین را میگوید. کاربران فهرستی را که آرام میگیرد میبخشند؛ برچسب «کمترین قیمت» را که غلط از آب درآمده نمیبخشند.
مدلسازی اتاق و rate plan، طوری که فرو نریزد
اینجاست که بیشتر اتصالهای هتل بیصدا شکست میخورند، و شکست ماهها بعد به شکل تیکت پشتیبانی ظاهر میشود، نه گزارش باگ.
مدل وسوسهانگیز، مدل تخت است: هتل فهرستی از پیشنهادها دارد و هر پیشنهاد یک نام اتاق و یک قیمت. خوب رندر میشود. بعد یک تأمینکننده «Deluxe King» و «Deluxe Room, 1 King Bed» را برای اتاقی برمیگرداند که آشکارا یکی است، تأمینکنندهی دیگری همان نام را برای دو اتاق واقعاً متفاوت میفرستد (یکی رو به شهر، یکی نه)، و سومی نرخی میدهد که قیمتش شبانه است در حالی که بقیه برای کل اقامت قیمت دادهاند. فهرست تخت نمیتواند بگوید با کدامیک سروکار دارید. فقط نشانشان میدهد.
مدلی که با تأمینکنندگان واقعی دوام بیاورد دستکم چهار سطح دارد و آنها را از هم جدا نگه میدارد:
| سطح | چه چیزی نگه میدارد | خطایی که باید از آن پرهیز کرد |
|---|---|---|
| هتل | شناسهی پایدار خودتان، نگاشتشده به کد هر تأمینکننده | استفاده از شناسهی هتلِ تأمینکننده بهعنوان کلید اصلی |
| اتاق | ظرفیت، چیدمان تخت، متن اصلی اتاق از تأمینکننده بدون تغییر | «مرتب کردن» نام اتاقها تا جایی که دو اتاق متفاوت یکی شوند |
| Rate plan | نوع بُرد (صبحانه و…)، قابلیت استرداد، نوع پرداخت، منبع | گنجاندن صبحانه یا قابلیت استرداد در نام اتاق |
| قیمت | جمع کل اقامت، ارز، مالیاتها و هزینههایی که داخل آن است و آنهایی که در هتل پرداخت میشود | نمایش رقم شبانه کنار ارقام کل اقامت، یا پنهان کردن هزینههای پرداختی هنگام ورود |
میتوانید با جای این مرزها مخالف باشید — برخی تیمها ظرفیت را سطح جداگانهای میکنند، که وقتی رزرو چنداتاقه میفروشید معقول است. کاری که نمیتوانید بکنید ادغام سطحهاست فقط چون رابط کاربری دو تا از آنها را نشان میدهد. رابط میتواند هنگام رندر تخت کند. داده نباید.
یک جزئیات جملهی خودش را میخواهد: توضیح خام اتاق از تأمینکننده را کنار هر نسخهی نرمالشده نگه دارید. وقتی مهمانی میرسد و اتاقی متفاوت از واچرش به او میدهند، اولین سؤال همه این است که تأمینکننده دقیقاً چه فرستاده بود.
قوانین کنسلی دادهاند، نه یک پاراگراف
بسیاری از تأمینکنندگان شرایط کنسلی را بهصورت متن آزاد میفرستند: «کنسلی رایگان تا ۳ روز پیش از ورود، پس از آن جریمهی یک شب.» بسیار وسوسهانگیز است که همین رشته را نمایش دهید و بروید سراغ کار بعدی.
نکنید. متن را نمیشود مقایسه، مرتب، فیلتر یا اجرا کرد. کاربر شما میخواهد فقط نرخهای قابل استرداد را ببیند. تیم مالی میخواهد بداند کدام رزروها از فردا غیرقابل استرداد میشوند تا آژانس پیش از گذشتن مهلت سراغ مشتری برود. فرایند پس از رزرو باید در لحظهای که مشتری دکمهی کنسلی را میزند، دقیقاً بگوید چقدر از او کسر میشود. هیچکدام از اینها روی یک جمله کار نمیکند.
هر قانون را بهصورت فهرستی مرتب از پنجرههای جریمه مدل کنید: از این لحظه تا آن لحظه، جریمه این مبلغ است (یا این سهم از اقامت، یا این تعداد شب). مرزها timestamp با منطقهی زمانیاند — منطقهی زمانی هتل، نه سرور شما و نه کاربر — چون «۳ روز پیش از ورود» بسته به اینکه نیمهشبِ چه کسی را حساب کنید، لحظهی متفاوتی است. متن اصلی تأمینکننده را کنار نسخهی ساختاریافته نگه دارید، نسخهی ساختاریافته را نمایش دهید، و ناهمخوانی میان این دو را چیزی برای بررسی بدانید، نه چیزی برای پنهان کردن.
و قانون را هنگام رزرو دوباره بررسی کنید، نه فقط هنگام جستوجو. قوانین میان این دو فراخوانی بیش از آنچه کسی انتظار دارد تغییر میکنند.
اشتباه در این کار واقعاً چه هزینهای دارد
جستوجوی کُند فروش را از دست میدهد، که بد است اما دیده میشود — بالاخره کسی شکایت میکند. شکستهای گران، شکستهای بیصدا هستند.
نرخی که قابل استرداد نمایش داده شده و تأمینکننده آن را غیرقابل استرداد میداند، یعنی اختلاف با مشتریای که اسکرینشات دارد، و معمولاً خود آژانس جریمه را میپردازد. قیمت شبانهای که بهعنوان جمع کل اقامت نمایش داده شود، اتاق را زیر قیمت تمامشده میفروشد تا روزی که کسی در حسابداری متوجه شود. اتاقی که با اتاق دیگری ادغام شده، خانوادهای چهارنفره را به اتاقی دونفره میفرستد. هزینههای پرداختی در هتل که هرگز نمایش داده نشدهاند، یک نظر پنجستاره را به chargeback تبدیل میکنند. هرکدام از اینها تصمیمی در مدلسازی است که در اسپرینت اول گرفته شده، معمولاً با برچسب «بعداً تمیزش میکنیم».
کش: چه چیزی را میتوانید نگه دارید و چه چیزی را نه
هر تیمی که به API هتل وصل میشود دیر یا زود میپرسد آیا میتواند نتایج را کش کند تا جستوجو سریعتر و ارزانتر شود. پاسخ برای برخی چیزها مثبت است، و مرز میان آنها از هر عدد عملکردی مهمتر است.
محتوای ثابت — نام هتل، نشانی، مختصات، عکسها، فهرست امکانات، توضیح اتاقها — بهندرت تغییر میکند و دقیقاً همان چیزی است که باید با جدیت در انبار خودتان کش کنید. شرایط تأمینکننده را دربارهی نحوهی ذخیره و نمایش آن بررسی کنید؛ برخی مجوزها محدودیت دارند. گرفتن زندهی آن در هر جستوجو بیدلیل کُند است.
نرخ و موجودی زنده داستان دیگری است. قیمت کششده حدسی است دربارهی آنچه تأمینکننده خواهد گرفت، و تأمینکنندگان به حدس شما احترام نمیگذارند. کش کوتاهمدت نتایج جستوجو برای نمایش یک صفحه میتواند پذیرفتنی باشد — به شرطی که هر مسیر رزرو پیش از گرفتن پول دوباره از تأمینکننده قیمت بگیرد، و رابط کاربری تغییر قیمت را نتیجهای عادی بداند نه خطا. برخی تأمینکنندگان هم نسبت تعداد جستوجو به رزرو را محدود میکنند؛ کش تهاجمی که ترافیک واقعی شما را از آنها پنهان کند، روزنهای نیست که ارزش تکیه کردن داشته باشد.
آنچه هرگز نباید کش شود، هر چیزی است که نمایندهی یک تعهد باشد: توکن قیمت نگهداشتهشده، کد رزرو، استعلام جریمهی کنسلی. اینها متعلق به یک کاربر و یک لحظهاند.
پیش از آنکه بگویید تمام شد
یک بررسی کوتاه، که ارزش دارد پیش از رزروهای واقعی روی اتصال خودتان اجرا کنید:
- جستوجو وضعیت تکمیل برمیگرداند و کلاینت پیش و پس از آن رفتار متفاوتی دارد.
- هتلها با شناسهی خودتان کلید خوردهاند و کد هر تأمینکننده به آن نگاشت شده است.
- اتاق، rate plan و قیمت در دادهی شما اشیای جدا هستند، هرچه صفحه نشان دهد.
- هر قیمت میگوید شبانه است یا برای کل اقامت، و چه چیزی هنگام ورود پرداخت میشود.
- قوانین کنسلی بهصورت پنجرههای زماندار جریمه با منطقهی زمانی هتل ذخیره شدهاند و متن اصلی هم نگه داشته شده است.
- مسیر رزرو پیش از گرفتن پول از هر کسی، دوباره قیمت میگیرد و قانون کنسلی را دوباره میخواند.
- هیچ چیزی که نمایندهی تعهد باشد هرگز از کش سرو نمیشود.
اگر دارید میسنجید که همهی اینها را جدا جدا روی تأمینکنندگان بسازید یا از پلتفرمی شروع کنید که پیشتر با این مسائل روبهرو شده، بخش قراردادی به اندازهی کد مهم است — نوشتهی ما دربارهی قراردادهای کانسالیدیتور هتل و نرخهای bedbank میگوید چه چیزهایی را باید بخواهید. API پرواز و هتل ما با گفتوگو باز میشود، نه با کلید سلفسرویس؛ اگر این مسیری است که میخواهید بررسی کنید، گفتوگو را در صفحهی travel APIs شروع کنید.
fan-out هیچوقت از بین نمیرود. کلاینت خوب فقط دیگر وانمود نمیکند که وجود ندارد.