API за наличност на хотели: дизайн за бавни доставчици

Задачата обикновено пристига с невинен вид. „Добавете търсене на хотели в страницата за резервации — доставчикът ни даде API за наличност на хотели, има sandbox, ще е за един спринт.“ Четете документацията, изпращате заявка за двама възрастни в София за три нощувки и идва отговор. После изпращате същата заявка за град с много повече места за настаняване и дълго, неприятно дълго нищо не се случва. Когато отговорът най-сетне пристигне, той е документ толкова голям, че вашият JSON парсер започва да преосмисля житейските си избори.
Точно тогава работата сменя формата си. Наличността на хотели не е справка в таблица. Тя е fan-out: един въпрос на вашия потребител се превръща в много въпроси към много доставчици, всеки от които отговаря със собствена скорост, със собствен речник и със собствена представа какво е „стая“. Клиентът, който изграждате, трябва да остане полезен, докато този fan-out все още се разгръща. Този текст е за проектирането на такъв клиент — написан за разработчик, който познава добре REST и JSON, но никога не е трябвало да обяснява на хотел защо невъзстановимата цена на гост е била показана като безплатно анулиране.
Защо API за наличност на хотели е по-бавно от endpoint-ите, с които сте свикнали
Отвън търсенето на полет и търсенето на хотел изглеждат сходно: излиза заявка, връщат се варианти с цени. Отдолу обаче не е същият проблем. Ако сте чели бележките ни за това какво всъщност включва интеграцията на API за резервация на полети, вече знаете, че цената от търсенето не винаги е цената, на която резервирате. Хотелите добавят втора трудност върху нея: обема.
Един-единствен град може да има стотици места за настаняване. Всяко място продава няколко типа стаи. Всеки тип стая се продава под няколко rate plans — със закуска, без, възстановима, невъзстановима, цена за членове, пакетна цена. И всеки rate plan може да идва от повече от един доставчик: bedbank, channel manager, директен договор, търговец на едро, с когото сте подписали, защото неговият allotment в даден хотел е бил по-добър от този на всички останали. Умножете всичко това и „простото“ търсене става голямо дърво, сглобено от няколко източника, които не са съгласни нито за имената, нито за идентификаторите.
Така че бавната част рядко е вашият код. Тя е най-бавният доставчик, когото сте решили да чакате.
Постепенни резултати или пълен отговор: изберете съзнателно
Има два честни начина да върнете резултати от търсене на хотели, а повечето интеграции завършват някъде нещастно по средата.
Чакате всичко. Бекендът прави fan-out, изчаква всеки доставчик да отговори или да изтече таймаутът, обединява, премахва дубликати, сортира и връща един пълен списък. Резултатът е чист: една заявка, един отговор, цени, които могат да се сравняват, защото всички са на масата. Цената е, че потребителят гледа индикатор за зареждане толкова дълго, колкото отнема на най-бавния ви доставчик. Всеки път.
Изпращате каквото имате. Бекендът стартира fan-out и веднага връща search handle. Клиентът периодично пита handle-а или държи отворен stream и получава резултатите на порции, докато доставчиците отговарят. Първите хотели се появяват бързо. Цената е сложност навсякъде другаде: списъкът се пренарежда, докато потребителят го чете, етикетът „най-евтино“ може да се премести, а хотел, дошъл от един доставчик, по-късно може да получи по-ниска цена от друг.
Ако интерфейсът ви е страница за търсене пред човек, постепенният подход почти винаги е правилният — човекът разглежда, не пуска пакетна задача, а страница, която видимо работи, побеждава страница, която тихо мисли. Ако потребителят е друга машина — задача за сравнение на цени, корпоративен инструмент за резервации, на който му трябва един окончателен отговор — чакането често е по-просто и правилно.
Каквото и да изберете, три правила държат постепенния клиент в здрав разум:
- Всяка порция носи състояние на завършване за търсенето като цяло, за да може клиентът да различи „още няма нови резултати“ от „повече резултати няма да има“.
- Резултатите се обединяват по стабилен ключ на хотела на сървъра, а не просто се добавят. Клиентът никога не бива сам да разбира, че две карти са една и съща сграда.
- Сортирането по цена е временно, докато търсенето не приключи, и интерфейсът го казва. Потребителите прощават на списък, който се успокоява; не прощават на етикет „най-ниска цена“, който се окаже грешен.
Моделиране на стаи и rate plans, които да не се сринат
Тук повечето хотелски интеграции се провалят тихо, а провалът излиза наяве месеци по-късно като заявка към поддръжката, а не като доклад за грешка.
Изкушаващият модел е плосък: хотелът има списък с оферти, всяка оферта има име на стая и цена. Изглежда добре на екрана. После един доставчик връща „Deluxe King“ и „Deluxe Room, 1 King Bed“ за очевидно една и съща стая, друг връща едно и също име за две наистина различни стаи (едната с изглед към града, другата без), а трети връща цена на нощувка, докато всички останали дават цена за целия престой. Плоският списък не може да ви каже кое от тези неща гледате. Той просто ги показва.
Модел, който оцелява при срещата с истински доставчици, има поне четири нива и ги държи отделно:
| Ниво | Какво съдържа | Грешката, която да избегнете |
|---|---|---|
| Хотел | Вашият собствен стабилен ID, свързан с кода на всеки доставчик | Да използвате hotel ID на доставчик като първичен ключ |
| Стая | Брой гости, разположение на леглата, оригиналният текст на стаята от доставчика без промяна | Да „почиствате“ имената на стаите, докато две различни стаи се слеят в една |
| Rate plan | Изхранване, възстановимост, начин на плащане, доставчикът, от който е дошъл | Да третирате закуската или възстановимостта като част от името на стаята |
| Цена | Общо за престоя, валута, кои данъци и такси са включени и кои се плащат в хотела | Да показвате цена на нощувка до цени за престой или да криете такси, платими при пристигане |
Може да спорите къде точно минават границите — някои екипи изнасят броя гости в отделно ниво, което е разумно, щом продавате резервации за повече стаи. Това, което не можете да направите, е да сливате нива, защото интерфейсът показва само две от тях. Интерфейсът може да изравни данните при показване. Самите данни — не.
Един детайл заслужава отделно изречение: пазете оригиналното описание на стаята от доставчика до всичко, което нормализирате. Когато гост пристигне и получи различна стая от тази във ваучера си, първото, което някой ще попита, е какво точно е изпратил доставчикът.
Условията за анулиране са данни, не абзац
Много доставчици връщат условията за анулиране като свободен текст: „Безплатно анулиране до 3 дни преди пристигане, след това такса от 1 нощувка.“ Много е изкушаващо да покажете този низ и да продължите.
Недейте. Текстът не може да се сравнява, сортира, филтрира или прилага. Вашият потребител иска да филтрира само възстановими цени. Финансовият отдел иска да знае кои резервации стават невъзстановими утре, за да може агенцията да се свърже с клиента преди изтичането на срока. Процесът след резервация трябва да каже на клиента, в момента, в който натисне „анулирай“, точно колко ще му струва. Нищо от това не работи върху едно изречение.
Моделирайте всяко условие като подреден списък от наказателни прозорци: от този момент до онзи таксата е толкова (или такъв дял от престоя, или толкова нощувки). Границите са времеви отпечатъци с часова зона — часовата зона на хотела, не на сървъра ви и не на потребителя — защото „3 дни преди пристигане“ означава различен момент в зависимост от чия полунощ броите. Пазете оригиналния текст на доставчика до структурираната версия, показвайте структурираната и третирайте несъответствие между тях като нещо за разследване, а не за скриване.
И проверявайте условията отново при резервацията, а не само при търсенето. Те се променят между двете заявки по-често, отколкото някой очаква.
Колко всъщност струва грешката
Бавното търсене ви струва конверсии — лошо, но видимо; някой ще се оплаче. Скъпите провали са тихите.
Цена, показана като възстановима, която доставчикът третира като невъзстановима, е спор с клиент, който има скрийншот, и обикновено агенцията сама плаща неустойката. Цена на нощувка, показана като обща цена за престоя, продава стаи под себестойност, докато някой в счетоводството не забележи. Стая, слята с друга стая, изпраща семейство от четирима в стая за двама. Такси, платими в хотела, които никога не са били показани, превръщат петзвезден отзив в chargeback. Всяко от тези неща е решение за модела, взето в първия спринт, обикновено под етикета „ще го оправим по-късно“.
Кеширане: какво може да пазите и какво не
Всеки екип, който интегрира хотелски API, рано или късно пита дали може да кешира резултатите, за да направи търсенето по-бързо и по-евтино. Отговорът е да, за някои неща — и границата между тях е по-важна от всяка цифра за производителност.
Статичното съдържание — имена на хотели, адреси, координати, снимки, списъци с удобства, описания на стаи — се променя рядко и е точно това, което трябва да кеширате, агресивно, в собственото си хранилище. Проверете условията на доставчика как може да го съхранявате и показвате; някои лицензи го ограничават. Да го извличате на живо при всяко търсене е бавно и без полза.
Цените и наличността на живо са друга история. Кеширана цена е предположение какво ще начисли доставчикът, а доставчиците не уважават вашите предположения. Краткотрайното кеширане на резултати от търсене може да е приемливо за показване на страница — стига всеки път към резервация да преизчислява цената при доставчика, преди да вземе пари, и интерфейсът да третира променена цена като нормален изход, а не като грешка. Някои доставчици също ограничават колко често може да търсите спрямо това колко често резервирате; агресивно кеширане, което крие реалния ви трафик от тях, не е вратичка, на която си струва да разчитате.
Това, което никога не бива да кеширате, е всичко, което представлява ангажимент: задържан ценови токен, номер на резервация, оферта за анулиране. Те принадлежат на един потребител и на един момент.
Преди да кажете, че е готово
Кратка проверка, която си струва да пуснете срещу собствената си интеграция, преди тя да поеме реални резервации:
- Търсенето връща състояние на завършване и клиентът се държи различно преди и след него.
- Хотелите имат за ключ вашия собствен ID, с кода на всеки доставчик, свързан с него.
- Стаята, rate plan-ът и цената са отделни обекти в данните ви, каквото и да показва екранът.
- Всяка цена казва дали е на нощувка или за престоя и какво се плаща при пристигане.
- Условията за анулиране се пазят като времеви наказателни прозорци в часовата зона на хотела, със запазен оригинален текст.
- Пътят към резервация преизчислява цената и препрочита условията, преди да таксува когото и да било.
- Нищо, което представлява ангажимент, никога не се връща от кеш.
Ако преценявате дали да изградите всичко това срещу отделни доставчици, или да започнете от платформа, която вече се е сблъскала с тези проблеми, договорната страна е толкова важна, колкото и кодът — нашият текст за договорите с хотелски консолидатори и bedbank цените разглежда какво да поискате. Нашите собствени API за полети и хотели се отварят чрез разговор, а не със самообслужващ се ключ; ако това е пътят, който искате да проучите, започнете разговора на страницата за travel APIs.
Fan-out-ът никога не изчезва. Добрият клиент просто спира да се преструва, че го няма.