API för hotelltillgänglighet: byggt för långsamma leverantörer

Ärendet ser oftast oskyldigt ut när det kommer. ”Lägg till hotellsök på bokningssidan — leverantören har gett oss ett API för hotelltillgänglighet, det finns en sandbox, borde ta en sprint.” Du läser dokumentationen, skickar en förfrågan för två vuxna i Stockholm i tre nätter, och ett svar kommer tillbaka. Sedan skickar du samma förfrågan för en stad med betydligt fler boenden, och ingenting händer under en lång, obekväm stund. När svaret väl kommer är det ett dokument så stort att din JSON-parser börjar fundera över sina livsval.
Där byter jobbet form. Hotelltillgänglighet är inte en uppslagning. Det är en fan-out: en fråga från din användare blir många frågor till många leverantörer, och var och en svarar i sin egen takt, med sitt eget ordförråd och med sin egen uppfattning om vad ett ”rum” är. Klienten du bygger måste förbli användbar medan den fan-outen fortfarande pågår. Den här texten handlar om att designa den klienten — skriven för en utvecklare som kan REST och JSON väl men aldrig har behövt förklara för ett hotell varför en gästs ej återbetalningsbara pris visades som fri avbokning.
Varför ett API för hotelltillgänglighet är långsammare än de endpoints du är van vid
Utifrån ser en flygsökning och en hotellsökning likadana ut: en fråga går ut, prissatta alternativ kommer tillbaka. Under ytan är det inte samma problem. Har du läst våra anteckningar om vad en API-integration för flygbokning faktiskt innebär vet du redan att priset du söker fram inte alltid är priset du bokar. Hotell lägger en andra svårighet ovanpå den: volym.
En enda stad kan rymma hundratals boenden. Varje boende säljer flera rumstyper. Varje rumstyp säljs under flera rate plans — med frukost, utan, återbetalningsbar, ej återbetalningsbar, medlemspris, paketpris. Och varje rate plan kan komma från mer än en leverantör: en bedbank, en channel manager, ett direktavtal, en grossist du skrev på med för att deras allotment på ett visst hotell var bättre än alla andras. Multiplicera ihop det och en ”enkel” sökning blir ett stort träd, sammansatt av flera källor som inte är överens om varken namn eller ID:n.
Så den långsamma delen är sällan din kod. Det är den långsammaste leverantören du valde att vänta på.
Progressiva resultat eller hela svaret: välj medvetet
Det finns två ärliga sätt att returnera hotellsökresultat, och de flesta integrationer hamnar någonstans olyckligt mittemellan.
Vänta på allt. Backend gör fan-out, väntar tills varje leverantör har svarat eller fått timeout, slår ihop, tar bort dubbletter, sorterar och returnerar en komplett lista. Resultatet är rent: en förfrågan, ett svar, priser som går att jämföra eftersom alla ligger på bordet. Priset är att användaren stirrar på en spinner så länge din långsammaste leverantör behöver. Varenda gång.
Skicka det du har. Backend startar fan-outen och returnerar direkt ett sök-handle. Klienten pollar handlet eller håller en ström öppen och får resultat i omgångar allteftersom leverantörerna svarar. De första hotellen dyker upp snabbt. Priset är komplexitet överallt annars: listan sorteras om medan användaren läser den, en ”billigast”-märkning kan flytta sig, och ett hotell som kom från en leverantör kan senare få ett billigare pris från en annan.
Är ditt gränssnitt en söksida framför en människa är det progressiva nästan alltid rätt — personen bläddrar, hen kör inget batchjobb, och en sida som synligt arbetar slår en sida som tyst tänker. Är konsumenten en annan maskin — ett prisjämförelsejobb, ett företagsbokningsverktyg som behöver ett definitivt svar — är det ofta enklare och korrekt att vänta.
Oavsett vad du väljer håller tre regler en progressiv klient vid sina sinnen:
- Varje omgång bär ett slutförandestatus för sökningen som helhet, så att klienten vet skillnaden mellan ”inga fler resultat än” och ”inga fler resultat alls”.
- Resultat slås ihop på en stabil hotellnyckel på servern, de läggs inte bara till. Klienten ska aldrig själv behöva lista ut att två kort är samma byggnad.
- Sortering på pris är preliminär tills sökningen är klar, och gränssnittet säger det. Användare förlåter en lista som sätter sig; de förlåter inte en ”lägsta pris”-etikett som visar sig vara fel.
Modellera rum och rate plans så att de inte kollapsar
Här misslyckas de flesta hotellintegrationer i tysthet, och misslyckandet dyker upp månader senare som ett supportärende snarare än en buggrapport.
Den lockande modellen är platt: ett hotell har en lista erbjudanden, varje erbjudande har ett rumsnamn och ett pris. Den renderar snyggt. Sedan returnerar en leverantör ”Deluxe King” och ”Deluxe Room, 1 King Bed” för vad som uppenbart är samma rum, en annan returnerar samma namn för två faktiskt olika rum (ett med stadsutsikt, ett utan), och en tredje returnerar ett pris per natt medan alla andra anger pris per vistelse. En platt lista kan inte tala om vilket av dessa du tittar på. Den visar dem bara.
En modell som överlever kontakten med riktiga leverantörer har minst fyra nivåer och håller isär dem:
| Nivå | Vad den innehåller | Misstaget att undvika |
|---|---|---|
| Hotell | Ditt eget stabila ID, mappat mot varje leverantörs kod | Att använda en leverantörs hotell-ID som primärnyckel |
| Rum | Beläggning, sängkonfiguration, leverantörens egen rumstext ordagrant | Att ”städa” rumsnamn tills två olika rum smälter ihop till ett |
| Rate plan | Måltider, återbetalningsbarhet, betalsätt, vilken leverantör det kom från | Att behandla frukost eller återbetalningsbarhet som en del av rumsnamnet |
| Pris | Totalt för vistelsen, valuta, vilka skatter och avgifter som ingår och vilka som betalas på hotellet | Att visa ett pris per natt bredvid priser per vistelse, eller dölja avgifter som betalas vid ankomst |
Man kan tycka olika om var gränserna går — vissa team bryter ut beläggning till en egen nivå, vilket är rimligt så fort du säljer bokningar med flera rum. Det du inte kan göra är att slå ihop nivåer för att gränssnittet bara visar två av dem. Gränssnittet får platta till vid rendering. Datan får inte.
En detalj förtjänar en egen mening: spara leverantörens ursprungliga rumsbeskrivning bredvid det du normaliserar. När en gäst kommer fram och får ett annat rum än det på vouchern är det första alla frågar vad leverantören faktiskt skickade.
Avbokningsvillkor är data, inte ett stycke text
Många leverantörer returnerar avbokningsvillkor som fritext: ”Fri avbokning fram till 3 dagar före ankomst, därefter debiteras 1 natt.” Det är väldigt frestande att visa den strängen och gå vidare.
Gör inte det. Text kan inte jämföras, sorteras, filtreras eller verkställas. Din användare vill filtrera fram återbetalningsbara priser. Ekonomiavdelningen vill veta vilka bokningar som blir ej återbetalningsbara i morgon, så att byrån hinner jaga kunden innan fristen går ut. Flödet efter bokning måste tala om för kunden, i samma ögonblick som hen trycker på avboka, exakt vad det kommer att kosta. Inget av det fungerar på en mening.
Modellera varje villkor som en ordnad lista av straffönster: från den här tidpunkten, till den där, är avgiften så här mycket (eller den här andelen av vistelsen, eller så här många nätter). Gränserna är tidsstämplar med tidszon — hotellets tidszon, inte din servers och inte användarens — eftersom ”3 dagar före ankomst” betyder olika ögonblick beroende på vems midnatt du räknar från. Spara leverantörens originaltext bredvid den strukturerade versionen, visa den strukturerade, och behandla en skillnad mellan dem som något att utreda snarare än något att dölja.
Och kontrollera villkoren igen vid bokning, inte bara vid sökning. De ändras mellan de två anropen oftare än någon tror.
Vad det faktiskt kostar att göra fel
En långsam sökning kostar dig konverteringar, vilket är illa men synligt — någon kommer att klaga. De dyra felen är de tysta.
Ett pris som visas som återbetalningsbart men som leverantören behandlar som ej återbetalningsbart är en tvist med en kund som har en skärmdump, och byrån brukar själv få betala straffavgiften. Ett pris per natt som visas som totalpris för vistelsen säljer rum under kostnad tills någon på ekonomi märker det. Ett rum som slagits ihop med ett annat rum skickar en familj på fyra till ett rum byggt för två. Avgifter som betalas på hotellet och aldrig visades förvandlar ett femstjärnigt omdöme till en chargeback. Var och en av dessa är ett modelleringsbeslut som togs i första sprinten, oftast under etiketten ”vi städar upp det sen”.
Cachning: vad du får spara och vad du inte får
Varje team som integrerar ett hotell-API frågar förr eller senare om det kan cacha resultat för att göra sökningen snabbare och billigare. Svaret är ja, för vissa saker — och gränsen mellan dem betyder mer än någon prestandasiffra.
Statiskt innehåll — hotellnamn, adresser, koordinater, foton, listor över bekvämligheter, rumsbeskrivningar — ändras sällan och är precis det du bör cacha, aggressivt, i ditt eget lager. Kontrollera leverantörens villkor för hur du får lagra och visa det; vissa licenser begränsar det. Att hämta det live vid varje sökning är långsamt utan någon vinst.
Livepriser och tillgänglighet är en annan sak. Ett cachat pris är en gissning om vad leverantören kommer att ta betalt, och leverantörer respekterar inte dina gissningar. Kortlivad cachning av sökresultat kan vara acceptabelt för att visa en sida — så länge varje bokningsväg prissätter om mot leverantören innan pengar tas, och gränssnittet behandlar ett ändrat pris som ett normalt utfall snarare än ett fel. Vissa leverantörer begränsar också hur ofta du får söka i förhållande till hur ofta du bokar; aggressiv cachning som döljer din verkliga trafik för dem är inget kryphål värt att lita på.
Det du aldrig får cacha är något som representerar ett åtagande: en hållen pristoken, en bokningsreferens, en avbokningsoffert. De tillhör en användare och ett ögonblick.
Innan du kallar det klart
En kort kontroll, värd att köra mot din egen integration innan den bär riktiga bokningar:
- Sökningen returnerar en slutförandestatus, och klienten beter sig olika före och efter den.
- Hotell har ditt eget ID som nyckel, med varje leverantörs kod mappad mot det.
- Rum, rate plan och pris är separata objekt i din data, vad skärmen än visar.
- Varje pris anger om det gäller per natt eller per vistelse, och vad som betalas vid ankomst.
- Avbokningsvillkor lagras som tidsatta straffönster i hotellets tidszon, med originaltexten kvar.
- Bokningsvägen prissätter om och läser villkoren på nytt innan den debiterar någon.
- Ingenting som representerar ett åtagande serveras någonsin från en cache.
Om du väger att bygga allt detta mot enskilda leverantörer mot att utgå från en plattform som redan har stött på de här problemen, så spelar avtalssidan lika stor roll som koden — vår text om avtal med hotellkonsolidatorer och bedbank-priser går igenom vad du ska be om. Våra egna API:er för flyg och hotell öppnas genom ett samtal, inte med en självbetjäningsnyckel; om det är den vägen du vill utforska, börja samtalet på sidan för travel APIs.
Fan-outen försvinner aldrig. En bra klient slutar bara låtsas att den inte finns.