API for hotelltilgjengelighet: bygget for trege leverandører

Oppgaven ser som regel uskyldig ut når den kommer. «Legg til hotellsøk på bookingsiden — leverandøren har gitt oss et API for hotelltilgjengelighet, det finnes en sandbox, burde ta en sprint.» Du leser dokumentasjonen, sender en forespørsel for to voksne i Oslo i tre netter, og et svar kommer tilbake. Så sender du den samme forespørselen for en by med langt flere overnattingssteder, og ingenting skjer på lenge, ubehagelig lenge. Når svaret endelig kommer, er det et dokument så stort at JSON-parseren din begynner å vurdere livsvalgene sine.
Det er der jobben skifter form. Hotelltilgjengelighet er ikke et oppslag. Det er en fan-out: ett spørsmål fra brukeren din blir mange spørsmål til mange leverandører, og hver av dem svarer i sitt eget tempo, med sitt eget vokabular og med sin egen idé om hva et «rom» er. Klienten du bygger, må forbli nyttig mens denne fan-outen fortsatt pågår. Denne teksten handler om å designe den klienten — skrevet for en utvikler som kan REST og JSON godt, men aldri har måttet forklare et hotell hvorfor en gjests ikke-refunderbare pris ble vist som gratis avbestilling.
Hvorfor et API for hotelltilgjengelighet er tregere enn endepunktene du er vant til
Utenfra ser et flysøk og et hotellsøk like ut: en forespørsel går ut, prissatte alternativer kommer tilbake. Under overflaten er det ikke det samme problemet. Har du lest notatene våre om hva en API-integrasjon for flybestilling faktisk innebærer, vet du allerede at prisen du søker frem, ikke alltid er prisen du booker. Hoteller legger en ekstra vanskelighet oppå den: volum.
En enkelt by kan ha hundrevis av overnattingssteder. Hvert sted selger flere romtyper. Hver romtype selges under flere rate plans — med frokost, uten, refunderbar, ikke-refunderbar, medlemspris, pakkepris. Og hver rate plan kan komme fra mer enn én leverandør: en bedbank, en channel manager, en direkte kontrakt, en grossist du signerte med fordi deres allotment på ett bestemt hotell var bedre enn alle andres. Gang det sammen, og et «enkelt» søk blir et stort tre, satt sammen fra flere kilder som verken er enige om navn eller ID-er.
Den trege delen er altså sjelden koden din. Det er den tregeste leverandøren du valgte å vente på.
Progressive resultater eller hele svaret: velg bevisst
Det finnes to ærlige måter å returnere hotellsøkeresultater på, og de fleste integrasjoner havner et ulykkelig sted midt imellom.
Vent på alt. Backend gjør fan-out, venter til hver leverandør har svart eller fått timeout, slår sammen, fjerner duplikater, sorterer og returnerer én komplett liste. Resultatet er rent: én forespørsel, ett svar, priser som kan sammenlignes fordi alle ligger på bordet. Prisen er at brukeren stirrer på en spinner så lenge den tregeste leverandøren din trenger. Hver eneste gang.
Send det du har. Backend starter fan-outen og returnerer umiddelbart et søke-handle. Klienten poller handlet eller holder en strøm åpen og mottar resultater i puljer etter hvert som leverandørene svarer. De første hotellene dukker raskt opp. Prisen er kompleksitet overalt ellers: listen sorteres om mens brukeren leser den, et «billigst»-merke kan flytte seg, og et hotell som kom fra én leverandør, kan senere få en billigere pris fra en annen.
Er grensesnittet ditt en søkeside foran et menneske, er det progressive nesten alltid riktig — personen blar, kjører ikke en batchjobb, og en side som synlig jobber, slår en side som tenker i stillhet. Er konsumenten en annen maskin — en prissammenligningsjobb, et bedriftsbookingverktøy som trenger ett endelig svar — er det ofte enklere og riktig å vente.
Uansett hva du velger, holder tre regler en progressiv klient ved sine fulle fem:
- Hver pulje bærer en fullføringsstatus for søket som helhet, slik at klienten skiller mellom «ingen flere resultater ennå» og «ingen flere resultater i det hele tatt».
- Resultater slås sammen på en stabil hotellnøkkel på serveren, de legges ikke bare til. Klienten skal aldri selv måtte finne ut at to kort er samme bygning.
- Sortering på pris er foreløpig til søket er ferdig, og grensesnittet sier det. Brukere tilgir en liste som setter seg; de tilgir ikke en «laveste pris»-etikett som viser seg å være feil.
Modellering av rom og rate plans så de ikke kollapser
Det er her de fleste hotellintegrasjoner feiler i stillhet, og feilen viser seg måneder senere som en supporthenvendelse heller enn en feilrapport.
Den fristende modellen er flat: et hotell har en liste med tilbud, hvert tilbud har et romnavn og en pris. Den ser pen ut på skjermen. Så returnerer én leverandør «Deluxe King» og «Deluxe Room, 1 King Bed» for åpenbart det samme rommet, en annen returnerer samme navn for to faktisk forskjellige rom (ett med byutsikt, ett uten), og en tredje returnerer en pris per natt mens alle andre oppgir pris per opphold. En flat liste kan ikke fortelle deg hvilket av disse du ser på. Den bare viser dem.
En modell som overlever møtet med ekte leverandører, har minst fire nivåer og holder dem adskilt:
| Nivå | Hva det inneholder | Feilen du må unngå |
|---|---|---|
| Hotell | Din egen stabile ID, koblet til hver leverandørs kode | Å bruke en leverandørs hotell-ID som primærnøkkel |
| Rom | Belegg, sengeoppsett, leverandørens egen romtekst ordrett | Å «rydde» i romnavn til to forskjellige rom smelter sammen til ett |
| Rate plan | Måltider, refunderbarhet, betalingsmåte, leverandøren den kom fra | Å behandle frokost eller refunderbarhet som en del av romnavnet |
| Pris | Totalt for oppholdet, valuta, hvilke skatter og gebyrer som er inkludert og hvilke som betales på hotellet | Å vise en pris per natt ved siden av priser per opphold, eller skjule gebyrer som betales ved ankomst |
Man kan være uenig om hvor grensene går — noen team skiller ut belegg som eget nivå, noe som er fornuftig så snart du selger bookinger med flere rom. Det du ikke kan, er å slå sammen nivåer fordi grensesnittet bare viser to av dem. Grensesnittet kan flate ut ved visning. Dataene kan ikke.
Én detalj fortjener sin egen setning: ta vare på leverandørens opprinnelige rombeskrivelse ved siden av det du normaliserer. Når en gjest ankommer og får et annet rom enn det på voucheren, er det første noen spør om, hva leverandøren faktisk sendte.
Avbestillingsregler er data, ikke et avsnitt
Mange leverandører returnerer avbestillingsvilkår som fritekst: «Gratis avbestilling frem til 3 dager før ankomst, deretter gebyr på 1 natt.» Det er svært fristende å vise den strengen og gå videre.
Ikke gjør det. Tekst kan ikke sammenlignes, sorteres, filtreres eller håndheves. Brukeren din vil filtrere på refunderbare priser. Økonomiavdelingen vil vite hvilke bookinger som blir ikke-refunderbare i morgen, slik at byrået rekker å nå kunden før fristen går ut. Flyten etter booking må fortelle kunden, i det øyeblikket hen trykker avbestill, nøyaktig hva det koster. Ingenting av dette fungerer på en setning.
Modeller hver regel som en ordnet liste med gebyrvinduer: fra dette tidspunktet, til det tidspunktet, er gebyret så mye (eller denne andelen av oppholdet, eller så mange netter). Grensene er tidsstempler med tidssone — hotellets tidssone, ikke serverens og ikke brukerens — fordi «3 dager før ankomst» betyr et annet øyeblikk avhengig av hvem sin midnatt du regner fra. Lagre leverandørens originaltekst ved siden av den strukturerte versjonen, vis den strukturerte, og behandle et avvik mellom dem som noe som skal undersøkes, ikke skjules.
Og sjekk reglene på nytt ved booking, ikke bare ved søk. De endrer seg mellom de to kallene oftere enn noen forventer.
Hva feilene faktisk koster
Et tregt søk koster deg konverteringer, noe som er ille, men synlig — noen kommer til å klage. De dyre feilene er de stille.
En pris vist som refunderbar som leverandøren behandler som ikke-refunderbar, er en tvist med en kunde som har et skjermbilde, og byrået ender som regel med å betale gebyret selv. En pris per natt vist som totalpris for oppholdet selger rom under kostpris til noen i regnskap oppdager det. Et rom slått sammen med et annet rom sender en familie på fire inn i et rom bygget for to. Gebyrer som betales på hotellet og aldri ble vist, gjør en femstjerners anmeldelse til en chargeback. Hver av disse er en modelleringsbeslutning tatt i første sprint, som regel under merkelappen «det rydder vi opp i senere».
Caching: hva du kan beholde og hva du ikke kan
Alle team som integrerer et hotell-API, spør før eller siden om de kan cache resultater for å gjøre søket raskere og billigere. Svaret er ja, for noen ting — og grensen mellom dem betyr mer enn noe ytelsestall.
Statisk innhold — hotellnavn, adresser, koordinater, bilder, fasilitetslister, rombeskrivelser — endrer seg sjelden og er nettopp det du bør cache, aggressivt, i ditt eget lager. Sjekk leverandørens vilkår for hvordan du kan lagre og vise det; noen lisenser begrenser det. Å hente det live ved hvert søk er tregt uten gevinst.
Live priser og tilgjengelighet er noe annet. En cachet pris er en gjetning på hva leverandøren vil ta betalt, og leverandører respekterer ikke gjetningene dine. Kortvarig caching av søkeresultater kan være akseptabelt for å vise en side — så lenge hver bookingvei prissetter på nytt mot leverandøren før det tas penger, og grensesnittet behandler en endret pris som et normalt utfall heller enn en feil. Noen leverandører begrenser også hvor ofte du kan søke i forhold til hvor ofte du booker; aggressiv caching som skjuler den reelle trafikken din for dem, er ikke et smutthull verdt å stole på.
Det du aldri skal cache, er noe som representerer en forpliktelse: et holdt pristoken, en bookingreferanse, et avbestillingstilbud. De tilhører én bruker og ett øyeblikk.
Før du kaller det ferdig
En kort sjekk som er verdt å kjøre mot din egen integrasjon før den bærer ekte bookinger:
- Søket returnerer en fullføringsstatus, og klienten oppfører seg ulikt før og etter den.
- Hoteller har din egen ID som nøkkel, med hver leverandørs kode koblet til den.
- Rom, rate plan og pris er separate objekter i dataene dine, uansett hva skjermen viser.
- Hver pris sier om den er per natt eller per opphold, og hva som betales ved ankomst.
- Avbestillingsregler lagres som tidsbestemte gebyrvinduer i hotellets tidssone, med originalteksten bevart.
- Bookingveien prissetter på nytt og leser reglene på nytt før den belaster noen.
- Ingenting som representerer en forpliktelse, serveres noensinne fra en cache.
Hvis du vurderer om du skal bygge alt dette mot enkeltleverandører eller starte fra en plattform som allerede har møtt disse problemene, betyr kontraktsiden like mye som koden — teksten vår om kontrakter med hotellkonsolidatorer og bedbank-priser går gjennom hva du bør be om. Våre egne API-er for fly og hotell åpnes gjennom en samtale, ikke med en selvbetjeningsnøkkel; er det veien du vil utforske, start samtalen på siden for travel APIs.
Fan-outen forsvinner aldri. En god klient slutter bare å late som om den ikke er der.