API til hoteltilgængelighed: bygget til langsomme leverandører

Opgaven ser som regel uskyldig ud, når den lander. „Tilføj hotelsøgning på bookingsiden — leverandøren har givet os et API til hoteltilgængelighed, der er en sandbox, det burde være en sprint.“ Du læser dokumentationen, sender en forespørgsel for to voksne i København i tre nætter, og der kommer et svar. Så sender du samme forespørgsel for en by med langt flere overnatningssteder, og der sker ingenting i lang, ubehagelig tid. Når svaret endelig kommer, er det et dokument så stort, at din JSON-parser begynder at overveje sine livsvalg.
Det er her, opgaven skifter form. Hoteltilgængelighed er ikke et opslag. Det er en fan-out: ét spørgsmål fra din bruger bliver til mange spørgsmål til mange leverandører, og hver af dem svarer i sit eget tempo, med sit eget ordforråd og med sin egen idé om, hvad et „værelse“ er. Klienten, du bygger, skal forblive brugbar, mens fan-outen stadig er i gang. Denne tekst handler om at designe den klient — skrevet til en udvikler, der kender REST og JSON godt, men aldrig har skullet forklare et hotel, hvorfor en gæsts ikke-refunderbare pris blev vist som gratis afbestilling.
Hvorfor et API til hoteltilgængelighed er langsommere end de endpoints, du er vant til
Udefra ligner en flysøgning og en hotelsøgning hinanden: en forespørgsel går ud, prissatte muligheder kommer tilbage. Nedenunder er det ikke det samme problem. Har du læst vores noter om, hvad en API-integration til flybooking reelt indebærer, ved du allerede, at prisen i søgningen ikke altid er prisen, du booker til. Hoteller lægger en ekstra vanskelighed oven i: volumen.
En enkelt by kan rumme hundredvis af overnatningssteder. Hvert sted sælger flere værelsestyper. Hver værelsestype sælges under flere rate plans — med morgenmad, uden, refunderbar, ikke-refunderbar, medlemspris, pakkepris. Og hver rate plan kan komme fra mere end én leverandør: en bedbank, en channel manager, en direkte kontrakt, en grossist, du skrev under med, fordi deres allotment på ét bestemt hotel var bedre end alle andres. Gang det sammen, og en „simpel“ søgning bliver et stort træ, samlet fra flere kilder, der hverken er enige om navne eller ID'er.
Den langsomme del er altså sjældent din kode. Det er den langsomste leverandør, du valgte at vente på.
Progressive resultater eller det fulde svar: vælg bevidst
Der er to ærlige måder at returnere hotelsøgeresultater på, og de fleste integrationer ender et ulykkeligt sted midt imellem.
Vent på det hele. Backend laver fan-out, venter på, at hver leverandør svarer eller rammer timeout, fletter, fjerner dubletter, sorterer og returnerer én komplet liste. Resultatet er rent: én forespørgsel, ét svar, priser der kan sammenlignes, fordi de alle ligger på bordet. Prisen er, at brugeren stirrer på en spinner, så længe din langsomste leverandør er om det. Hver eneste gang.
Send det, du har. Backend starter fan-outen og returnerer straks et søge-handle. Klienten poller handlet eller holder en stream åben og modtager resultater i portioner, efterhånden som leverandørerne svarer. De første hoteller dukker hurtigt op. Prisen er kompleksitet alle andre steder: listen omrokeres, mens brugeren læser den, et „billigst“-mærke kan flytte sig, og et hotel fra én leverandør kan senere få en billigere pris fra en anden.
Er din brugerflade en søgeside foran et menneske, er det progressive næsten altid rigtigt — personen browser, kører ikke et batchjob, og en side, der synligt arbejder, slår en side, der tænker i stilhed. Er forbrugeren en anden maskine — et prissammenligningsjob, et virksomhedsbookingværktøj, der skal have ét endeligt svar — er det ofte enklere og korrekt at vente.
Uanset hvad du vælger, holder tre regler en progressiv klient ved sine fulde fem:
- Hver portion bærer en fuldførelsesstatus for søgningen som helhed, så klienten kender forskel på „ingen flere resultater endnu“ og „ingen flere resultater overhovedet“.
- Resultater flettes på en stabil hotelnøgle på serveren, de tilføjes ikke bare. Klienten skal aldrig selv finde ud af, at to kort er den samme bygning.
- Sortering efter pris er foreløbig, indtil søgningen er færdig, og brugerfladen siger det. Brugere tilgiver en liste, der falder på plads; de tilgiver ikke en „laveste pris“-etiket, der viser sig at være forkert.
Modellering af værelser og rate plans, så de ikke kollapser
Det er her, de fleste hotelintegrationer fejler i stilhed, og fejlen viser sig måneder senere som en supporthenvendelse frem for en fejlrapport.
Den fristende model er flad: et hotel har en liste af tilbud, hvert tilbud har et værelsesnavn og en pris. Den ser pæn ud på skærmen. Så returnerer én leverandør „Deluxe King“ og „Deluxe Room, 1 King Bed“ for åbenlyst det samme værelse, en anden returnerer samme navn for to reelt forskellige værelser (ét med byudsigt, ét uden), og en tredje returnerer en pris per nat, mens alle andre angiver pris per ophold. En flad liste kan ikke fortælle dig, hvilken af delene du kigger på. Den viser dem bare.
En model, der overlever mødet med rigtige leverandører, har mindst fire niveauer og holder dem adskilt:
| Niveau | Hvad det indeholder | Fejlen, der skal undgås |
|---|---|---|
| Hotel | Dit eget stabile ID, mappet til hver leverandørs kode | At bruge en leverandørs hotel-ID som primærnøgle |
| Værelse | Belægning, sengeopsætning, leverandørens egen værelsestekst ordret | At „rydde op“ i værelsesnavne, til to forskellige værelser smelter sammen til ét |
| Rate plan | Forplejning, refunderbarhed, betalingsform, hvilken leverandør det kom fra | At behandle morgenmad eller refunderbarhed som en del af værelsesnavnet |
| Pris | Samlet for opholdet, valuta, hvilke skatter og gebyrer der er inkluderet, og hvilke der betales på hotellet | At vise en pris per nat ved siden af priser per ophold eller skjule gebyrer, der betales ved ankomst |
Man kan være uenig om, hvor grænserne går — nogle teams trækker belægning ud som sit eget niveau, hvilket giver mening, så snart du sælger bookinger med flere værelser. Det, du ikke kan, er at slå niveauer sammen, fordi brugerfladen kun viser to af dem. Brugerfladen må gerne flade ud ved visning. Dataene må ikke.
Én detalje fortjener sin egen sætning: gem leverandørens oprindelige værelsesbeskrivelse ved siden af det, du normaliserer. Når en gæst ankommer og får et andet værelse end det på voucheren, er det første, nogen spørger om, hvad leverandøren faktisk sendte.
Afbestillingsregler er data, ikke et afsnit
Mange leverandører returnerer afbestillingsvilkår som fritekst: „Gratis afbestilling indtil 3 dage før ankomst, derefter gebyr på 1 nat.“ Det er meget fristende at vise den streng og komme videre.
Lad være. Tekst kan ikke sammenlignes, sorteres, filtreres eller håndhæves. Din bruger vil filtrere på refunderbare priser. Økonomiafdelingen vil vide, hvilke bookinger der bliver ikke-refunderbare i morgen, så bureauet kan nå at fange kunden, før fristen udløber. Flowet efter booking skal fortælle kunden, i det øjeblik der trykkes på afbestil, præcis hvad det koster. Intet af det virker på en sætning.
Modellér hver regel som en ordnet liste af gebyrvinduer: fra dette tidspunkt, til hint, er gebyret så meget (eller denne andel af opholdet, eller så mange nætter). Grænserne er tidsstempler med tidszone — hotellets tidszone, ikke din servers og ikke brugerens — fordi „3 dage før ankomst“ betyder et andet øjeblik, alt efter hvis midnat du regner fra. Gem leverandørens originaltekst ved siden af den strukturerede version, vis den strukturerede, og behandl en uoverensstemmelse mellem dem som noget, der skal undersøges, ikke skjules.
Og tjek reglerne igen ved booking, ikke kun ved søgning. De ændrer sig mellem de to kald oftere, end nogen forventer.
Hvad fejlene reelt koster
En langsom søgning koster dig konverteringer, hvilket er skidt, men synligt — nogen vil klage. De dyre fejl er de stille.
En pris, der vises som refunderbar, men som leverandøren behandler som ikke-refunderbar, er en tvist med en kunde, der har et skærmbillede, og bureauet ender som regel selv med at betale gebyret. En pris per nat, der vises som samlet pris for opholdet, sælger værelser under kostpris, indtil nogen i bogholderiet opdager det. Et værelse, der er slået sammen med et andet værelse, sender en familie på fire ind i et værelse bygget til to. Gebyrer, der betales på hotellet og aldrig blev vist, forvandler en femstjernet anmeldelse til en chargeback. Hver af dem er en modelleringsbeslutning truffet i første sprint, som regel under overskriften „det rydder vi op i senere“.
Caching: hvad du må gemme, og hvad du ikke må
Alle teams, der integrerer et hotel-API, spørger før eller siden, om de kan cache resultater for at gøre søgningen hurtigere og billigere. Svaret er ja, for nogle ting — og grænsen mellem dem betyder mere end noget performancetal.
Statisk indhold — hotelnavne, adresser, koordinater, fotos, lister over faciliteter, værelsesbeskrivelser — ændrer sig sjældent og er netop det, du bør cache, aggressivt, i dit eget lager. Tjek leverandørens vilkår for, hvordan du må gemme og vise det; nogle licenser begrænser det. At hente det live ved hver søgning er langsomt uden gevinst.
Live priser og tilgængelighed er en anden sag. En cachet pris er et gæt på, hvad leverandøren vil opkræve, og leverandører respekterer ikke dine gæt. Kortvarig caching af søgeresultater kan være acceptabel til at vise en side — så længe hver bookingvej genprissætter hos leverandøren, før der tages penge, og brugerfladen behandler en ændret pris som et normalt udfald frem for en fejl. Nogle leverandører begrænser også, hvor ofte du må søge i forhold til, hvor ofte du booker; aggressiv caching, der skjuler din reelle trafik for dem, er ikke et smuthul, der er værd at stole på.
Det, du aldrig må cache, er noget, der repræsenterer en forpligtelse: et holdt pristoken, en bookingreference, et afbestillingstilbud. De tilhører én bruger og ét øjeblik.
Før du kalder det færdigt
Et kort tjek, der er værd at køre mod din egen integration, før den bærer rigtige bookinger:
- Søgningen returnerer en fuldførelsesstatus, og klienten opfører sig forskelligt før og efter den.
- Hoteller har dit eget ID som nøgle, med hver leverandørs kode mappet til det.
- Værelse, rate plan og pris er separate objekter i dine data, uanset hvad skærmen viser.
- Hver pris angiver, om den er per nat eller per ophold, og hvad der betales ved ankomst.
- Afbestillingsregler gemmes som tidsbestemte gebyrvinduer i hotellets tidszone, med originalteksten bevaret.
- Bookingvejen genprissætter og genlæser reglerne, før den trækker penge fra nogen.
- Intet, der repræsenterer en forpligtelse, serveres nogensinde fra en cache.
Hvis du overvejer, om du skal bygge alt dette mod enkelte leverandører eller starte fra en platform, der allerede har mødt disse problemer, betyder kontraktsiden lige så meget som koden — vores tekst om kontrakter med hotelkonsolidatorer og bedbank-priser gennemgår, hvad du skal bede om. Vores egne API'er til fly og hotel åbnes gennem en samtale, ikke med en selvbetjeningsnøgle; er det den vej, du vil undersøge, så start samtalen på siden om travel APIs.
Fan-outen forsvinder aldrig. En god klient holder bare op med at lade som om, den ikke er der.