Hotel-Verfügbarkeits-API: Design für langsame Lieferanten

Das Ticket kommt meist harmlos daher: „Hotelsuche auf der Buchungsseite ergänzen — der Lieferant hat uns eine Hotel-Verfügbarkeits-API gegeben, es gibt eine Sandbox, das ist ein Sprint.“ Sie lesen die Doku, schicken eine Anfrage für zwei Erwachsene in Wien für drei Nächte, und eine Antwort kommt zurück. Dann schicken Sie dieselbe Anfrage für eine Stadt mit deutlich mehr Unterkünften, und eine lange, unangenehme Weile kommt gar nichts. Wenn doch, ist es ein Dokument, groß genug, dass Ihr JSON-Parser über seine Berufswahl nachdenkt.
Genau in diesem Moment ändert die Aufgabe ihre Form. Hotelverfügbarkeit ist kein Lookup. Sie ist ein Fan-out: Aus einer Frage des Nutzers werden viele Fragen an viele Lieferanten, und jeder antwortet in seinem eigenen Tempo, mit seinem eigenen Vokabular und seiner eigenen Vorstellung davon, was ein „Zimmer“ ist. Der Client, den Sie bauen, muss nützlich bleiben, solange dieser Fan-out noch läuft. Dieser Beitrag handelt vom Entwurf genau dieses Clients — geschrieben für Entwickler, die REST und JSON gut kennen, aber noch nie einem Hotel erklären mussten, warum ein nicht erstattbarer Tarif dem Gast als kostenlos stornierbar angezeigt wurde.
Warum eine Hotel-Verfügbarkeits-API langsamer ist als gewohnte Endpunkte
Flugsuche und Hotelsuche sehen von außen ähnlich aus: Eine Anfrage geht raus, bepreiste Optionen kommen zurück. Darunter ist es nicht dasselbe Problem. Wer unsere Notizen dazu gelesen hat, was eine Flugbuchungs-API-Integration wirklich bedeutet, weiß bereits, dass der gesuchte Preis nicht immer der gebuchte ist. Hotels legen eine zweite Schwierigkeit obendrauf: Volumen.
Eine einzige Stadt kann Hunderte Unterkünfte haben. Jede verkauft mehrere Zimmertypen. Jeder Zimmertyp wird unter mehreren Rate Plans verkauft — mit Frühstück, ohne, erstattbar, nicht erstattbar, Mitgliedertarif, Pakettarif. Jeder Rate Plan kann von mehreren Lieferanten stammen: einer Bedbank, einem Channel Manager, einem Direktvertrag, einem Großhändler, mit dem Sie unterschrieben haben, weil sein Allotment in einem bestimmten Hotel besser war als das aller anderen. Multiplizieren Sie das aus, und eine „einfache“ Suche ist ein großer Baum, zusammengesetzt aus Quellen, die sich weder auf Namen noch auf IDs einigen.
Der langsame Teil ist also selten Ihr Code. Es ist der langsamste Lieferant, auf den Sie zu warten beschlossen haben.
Progressive Ergebnisse oder vollständige Antwort: bewusst entscheiden
Es gibt zwei ehrliche Arten, Hotelsuchergebnisse zurückzugeben, und die meisten Integrationen landen unglücklich irgendwo dazwischen.
Auf alle warten. Ihr Backend verteilt die Anfrage, wartet, bis jeder Lieferant geantwortet hat oder in den Timeout läuft, führt zusammen, dedupliziert, sortiert und liefert eine vollständige Liste. Das Ergebnis ist sauber: eine Anfrage, eine Antwort, vergleichbare Preise, weil alle auf dem Tisch liegen. Der Preis: Der Nutzer starrt jedes Mal so lange auf einen Spinner, wie Ihr langsamster Lieferant braucht.
Streamen, was da ist. Ihr Backend startet den Fan-out und gibt sofort ein Such-Handle zurück. Der Client pollt das Handle oder hält einen Stream offen und erhält Ergebnisse in Batches, sobald Lieferanten antworten. Die ersten Hotels erscheinen schnell. Der Preis ist Komplexität an allen anderen Stellen: Die Liste sortiert sich um, während der Nutzer sie liest, ein „Günstigster“-Badge kann wandern, und ein Hotel, das über einen Lieferanten kam, bekommt später vielleicht von einem anderen einen günstigeren Tarif.
Ist Ihre Oberfläche eine Suchseite vor einem Menschen, ist progressiv fast immer richtig — die Person stöbert, sie startet keinen Batch-Job, und eine Seite, die sichtbar arbeitet, schlägt eine Seite, die still nachdenkt. Ist der Konsument eine andere Maschine — ein Preisvergleichsjob, ein Firmenbuchungstool, das eine endgültige Antwort braucht —, ist Warten oft einfacher und korrekt.
Egal wofür Sie sich entscheiden, drei Regeln halten einen progressiven Client bei Verstand:
- Jeder Batch trägt einen Abschlussstatus der gesamten Suche, damit der Client „noch keine weiteren Ergebnisse“ von „keine weiteren Ergebnisse mehr“ unterscheiden kann.
- Ergebnisse werden serverseitig über einen stabilen Hotel-Schlüssel zusammengeführt, nicht einfach angehängt. Der Client sollte nie selbst herausfinden müssen, dass zwei Karten dasselbe Gebäude sind.
- Die Sortierung nach Preis ist vorläufig, bis die Suche abgeschlossen ist, und die Oberfläche sagt das. Nutzer verzeihen eine Liste, die sich setzt; sie verzeihen kein „Bester Preis“-Label, das sich als falsch herausstellt.
Zimmer und Rate Plans so modellieren, dass nichts zusammenbricht
Hier scheitern die meisten Hotelintegrationen leise, und das Scheitern zeigt sich Monate später als Support-Ticket statt als Bug-Report.
Das verlockende Modell ist flach: Ein Hotel hat eine Liste von Angeboten, jedes Angebot hat einen Zimmernamen und einen Preis. Das rendert hübsch. Dann liefert ein Lieferant „Deluxe King“ und „Deluxe Room, 1 King Bed“ für offensichtlich dasselbe Zimmer, ein anderer liefert denselben Namen für zwei tatsächlich verschiedene Zimmer (eines mit Stadtblick, eines ohne), und ein dritter liefert einen Preis pro Nacht, während alle anderen pro Aufenthalt angeben. Eine flache Liste kann Ihnen nicht sagen, welchen dieser Fälle Sie vor sich haben. Sie zeigt sie nur an.
Ein Modell, das den Kontakt mit echten Lieferanten übersteht, hat mindestens vier Ebenen und hält sie getrennt:
| Ebene | Was sie enthält | Der Fehler, den man vermeiden muss |
|---|---|---|
| Hotel | Ihre eigene stabile ID, auf den Code jedes Lieferanten gemappt | Die Hotel-ID eines Lieferanten als Primärschlüssel verwenden |
| Zimmer | Belegung, Bettenkonfiguration, Zimmertext des Lieferanten wörtlich aufbewahrt | Zimmernamen so lange „bereinigen“, bis zwei verschiedene Zimmer verschmelzen |
| Rate Plan | Verpflegung, Erstattbarkeit, Zahlungsart, Herkunftslieferant | Frühstück oder Erstattbarkeit als Teil des Zimmernamens behandeln |
| Preis | Gesamtbetrag für den Aufenthalt, Währung, enthaltene Steuern und Gebühren und was vor Ort zu zahlen ist | Einen Nachtpreis neben Aufenthaltspreisen zeigen oder bei Ankunft fällige Gebühren verstecken |
Über die Grenzziehung kann man streiten — manche Teams geben der Belegung eine eigene Ebene, was sinnvoll ist, sobald Sie Buchungen mit mehreren Zimmern verkaufen. Was Sie nicht tun dürfen: Ebenen zusammenlegen, weil die Oberfläche nur zwei davon zeigt. Die Oberfläche darf beim Rendern abflachen. Die Daten nicht.
Ein Detail verdient einen eigenen Satz: Bewahren Sie die Rohbeschreibung des Zimmers vom Lieferanten neben allem auf, was Sie normalisieren. Wenn ein Gast ankommt und ein anderes Zimmer bekommt als auf seinem Voucher, lautet die erste Frage aller Beteiligten: Was hat der Lieferant eigentlich geschickt?
Stornobedingungen sind Daten, kein Absatz
Viele Lieferanten liefern Stornobedingungen als Freitext: „Kostenlose Stornierung bis 3 Tage vor Anreise, danach 1 Nacht Gebühr.“ Es ist sehr verlockend, diesen String anzuzeigen und weiterzumachen.
Tun Sie es nicht. Text lässt sich nicht vergleichen, sortieren, filtern oder durchsetzen. Ihr Nutzer will auf erstattbare Tarife filtern. Ihre Buchhaltung will wissen, welche Buchungen morgen nicht mehr erstattbar sind, damit das Reisebüro den Kunden vor Fristablauf erreicht. Ihr Post-Booking-Flow muss dem Kunden in dem Moment, in dem er auf Stornieren klickt, genau sagen, was berechnet wird. Nichts davon funktioniert mit einem Satz.
Modellieren Sie jede Bedingung als geordnete Liste von Gebührenfenstern: von diesem Zeitpunkt bis zu jenem beträgt die Gebühr diesen Betrag (oder diesen Anteil am Aufenthalt, oder so viele Nächte). Die Grenzen sind Zeitstempel mit Zeitzone — der des Hotels, nicht der Ihres Servers und nicht der des Nutzers —, denn „3 Tage vor Anreise“ bedeutet je nach zugrunde gelegter Mitternacht einen anderen Moment. Speichern Sie den Originaltext des Lieferanten neben der strukturierten Fassung, zeigen Sie die strukturierte an und behandeln Sie Abweichungen zwischen beiden als etwas, dem man nachgeht, nicht als etwas, das man versteckt.
Und prüfen Sie die Bedingung bei der Buchung erneut, nicht nur bei der Suche. Bedingungen ändern sich zwischen den beiden Aufrufen häufiger, als man denkt.
Was ein Fehler wirklich kostet
Eine langsame Suche kostet Conversions — schlecht, aber sichtbar, irgendwer beschwert sich. Die teuren Fehler sind die leisen.
Ein als erstattbar angezeigter Tarif, den der Lieferant als nicht erstattbar behandelt, ist ein Streit mit einem Kunden, der einen Screenshot hat, und meist zahlt das Reisebüro die Gebühr selbst. Ein Nachtpreis, der als Aufenthaltssumme angezeigt wird, verkauft Zimmer unter Einstand, bis es jemandem in der Buchhaltung auffällt. Ein mit einem anderen verschmolzenes Zimmer schickt eine vierköpfige Familie in ein Zimmer für zwei. Nie angezeigte Gebühren, die im Hotel fällig werden, machen aus einer Fünf-Sterne-Bewertung eine Rückbuchung. Jeder dieser Fälle ist eine Modellierungsentscheidung aus dem ersten Sprint, meist unter dem Etikett „räumen wir später auf“.
Caching: was Sie behalten dürfen und was nicht
Jedes Team, das eine Hotel-API integriert, fragt irgendwann, ob es Ergebnisse cachen darf, um die Suche schneller und günstiger zu machen. Die Antwort lautet: ja, für manches — und die Grenze dazwischen ist wichtiger als jede Performance-Kennzahl.
Statischer Content — Hotelnamen, Adressen, Koordinaten, Fotos, Ausstattungslisten, Zimmerbeschreibungen — ändert sich selten und ist genau das, was Sie großzügig im eigenen Speicher cachen sollten. Prüfen Sie die Bedingungen des Lieferanten, wie Sie ihn speichern und anzeigen dürfen; manche Lizenzen schränken das ein. Ihn bei jeder Suche live abzurufen ist langsam und bringt nichts.
Live-Tarife und Verfügbarkeit sind eine andere Sache. Ein gecachter Preis ist eine Vermutung darüber, was der Lieferant berechnen wird, und Lieferanten halten sich nicht an Ihre Vermutungen. Kurzlebiges Caching von Suchergebnissen kann für die Anzeige einer Seite vertretbar sein — sofern jeder Buchungspfad vor dem Kassieren beim Lieferanten neu bepreist und die Oberfläche einen geänderten Preis als normales Ergebnis statt als Fehler behandelt. Manche Lieferanten begrenzen zudem das Verhältnis von Suchen zu Buchungen; aggressives Caching, das Ihren echten Traffic vor ihnen verbirgt, ist kein Schlupfloch, auf das man sich verlassen sollte.
Niemals cachen dürfen Sie alles, was eine Verpflichtung darstellt: ein gehaltenes Preis-Token, eine Buchungsreferenz, ein Stornoangebot. Das gehört einem Nutzer und einem Moment.
Bevor Sie es fertig nennen
Eine kurze Prüfung, die sich lohnt, bevor Ihre Integration echte Buchungen trägt:
- Die Suche liefert einen Abschlussstatus, und der Client verhält sich davor und danach unterschiedlich.
- Hotels sind über Ihre eigene ID verschlüsselt, mit dem Code jedes Lieferanten darauf gemappt.
- Zimmer, Rate Plan und Preis sind getrennte Objekte in Ihren Daten, egal was der Bildschirm zeigt.
- Jeder Preis sagt, ob er pro Nacht oder pro Aufenthalt gilt und was bei Ankunft fällig ist.
- Stornobedingungen sind als zeitlich begrenzte Gebührenfenster in der Zeitzone des Hotels gespeichert, der Originaltext bleibt erhalten.
- Der Buchungspfad bepreist neu und liest die Bedingung erneut, bevor er irgendwen belastet.
- Nichts, was eine Verpflichtung darstellt, wird jemals aus einem Cache ausgeliefert.
Wenn Sie abwägen, ob Sie all das gegen einzelne Lieferanten selbst bauen oder auf einer Plattform aufsetzen, die diese Probleme schon kennt, zählt die Vertragsseite so viel wie der Code — unser Beitrag zu Hotel-Consolidator-Verträgen und Bedbank-Raten zeigt, was Sie verlangen sollten. Unsere eigenen Flug- und Hotel-APIs werden über ein Gespräch freigeschaltet, nicht über einen Self-Service-Key; wenn Sie diesen Weg prüfen wollen, beginnen Sie das Gespräch auf der Seite zu den Reise-APIs.
Der Fan-out verschwindet nie. Ein guter Client hört einfach auf, so zu tun, als gäbe es ihn nicht.