API διαθεσιμότητας ξενοδοχείων για αργούς προμηθευτές

Το ticket συνήθως φτάνει με αθώα όψη. «Προσθέστε αναζήτηση ξενοδοχείων στη σελίδα κράτησης — ο προμηθευτής μάς έδωσε ένα API διαθεσιμότητας ξενοδοχείων, υπάρχει sandbox, ένα sprint θα είναι.» Διαβάζεις την τεκμηρίωση, στέλνεις αίτημα για δύο ενήλικες στην Αθήνα για τρεις νύχτες, και έρχεται απάντηση. Μετά στέλνεις το ίδιο αίτημα για μια πόλη με πολύ περισσότερα καταλύματα, και για ένα μακρύ, άβολο διάστημα δεν έρχεται τίποτα. Όταν τελικά έρθει, είναι ένα έγγραφο τόσο μεγάλο που ο JSON parser σου αρχίζει να αναθεωρεί τις επιλογές της ζωής του.
Εκείνη τη στιγμή η δουλειά αλλάζει σχήμα. Η διαθεσιμότητα ξενοδοχείων δεν είναι αναζήτηση σε πίνακα. Είναι fan-out: μία ερώτηση του χρήστη σου γίνεται πολλές ερωτήσεις προς πολλούς προμηθευτές, και ο καθένας απαντά με τη δική του ταχύτητα, στο δικό του λεξιλόγιο, με τη δική του ιδέα για το τι είναι «δωμάτιο». Ο client που χτίζεις πρέπει να μένει χρήσιμος όσο αυτό το fan-out ακόμη εξελίσσεται. Το κείμενο αυτό αφορά τον σχεδιασμό αυτού του client — και γράφεται για έναν developer που ξέρει καλά REST και JSON, αλλά δεν χρειάστηκε ποτέ να εξηγήσει σε ξενοδοχείο γιατί ένα non-refundable rate εμφανίστηκε στον πελάτη ως δωρεάν ακύρωση.
Γιατί ένα API διαθεσιμότητας ξενοδοχείων είναι πιο αργό από ό,τι έχεις συνηθίσει
Από έξω, μια αναζήτηση πτήσης και μια αναζήτηση ξενοδοχείου μοιάζουν: φεύγει ένα ερώτημα, επιστρέφουν επιλογές με τιμές. Από κάτω, δεν είναι το ίδιο πρόβλημα. Αν έχεις διαβάσει τις σημειώσεις μας για το τι περιλαμβάνει πραγματικά η ενσωμάτωση ενός API κρατήσεων πτήσεων, ξέρεις ήδη ότι η τιμή που βλέπεις στην αναζήτηση δεν είναι πάντα η τιμή που κλείνεις. Τα ξενοδοχεία προσθέτουν μια δεύτερη δυσκολία πάνω σε αυτή: τον όγκο.
Μία μόνο πόλη μπορεί να έχει εκατοντάδες καταλύματα. Κάθε κατάλυμα πουλά αρκετούς τύπους δωματίων. Κάθε τύπος δωματίου πουλιέται με αρκετά rate plans — με πρωινό, χωρίς, επιστρέψιμο, μη επιστρέψιμο, τιμή μέλους, τιμή πακέτου. Και κάθε rate plan μπορεί να έρχεται από περισσότερους από έναν προμηθευτές: ένα bedbank, έναν channel manager, ένα απευθείας συμβόλαιο, έναν wholesaler που υπέγραψες επειδή το allotment του σε ένα συγκεκριμένο ξενοδοχείο ήταν καλύτερο από όλων των άλλων. Πολλαπλασίασέ τα και η «απλή» αναζήτηση γίνεται ένα μεγάλο δέντρο, συναρμολογημένο από πηγές που δεν συμφωνούν ούτε στα ονόματα ούτε στα IDs.
Άρα το αργό κομμάτι σπάνια είναι ο δικός σου κώδικας. Είναι ο πιο αργός προμηθευτής που αποφάσισες να περιμένεις.
Προοδευτικά αποτελέσματα ή πλήρης απάντηση: διάλεξε συνειδητά
Υπάρχουν δύο έντιμοι τρόποι να επιστρέψεις αποτελέσματα αναζήτησης ξενοδοχείων, και οι περισσότερες ενσωματώσεις καταλήγουν κάπου δυστυχισμένα στη μέση.
Περιμένεις τα πάντα. Το backend κάνει fan-out, περιμένει κάθε προμηθευτή να απαντήσει ή να λήξει το timeout, συγχωνεύει, αφαιρεί διπλότυπα, ταξινομεί και επιστρέφει μία πλήρη λίστα. Το αποτέλεσμα είναι καθαρό: ένα αίτημα, μία απάντηση, τιμές που συγκρίνονται γιατί είναι όλες στο τραπέζι. Το κόστος είναι ότι ο χρήστης κοιτάζει ένα spinner για όσο χρειάζεται ο πιο αργός προμηθευτής σου, κάθε φορά.
Στέλνεις ό,τι έχεις. Το backend ξεκινά το fan-out και επιστρέφει αμέσως ένα search handle. Ο client κάνει polling στο handle ή κρατά ανοιχτό ένα stream και παίρνει αποτελέσματα σε παρτίδες, καθώς απαντούν οι προμηθευτές. Τα πρώτα ξενοδοχεία εμφανίζονται γρήγορα. Το κόστος είναι πολυπλοκότητα παντού αλλού: η λίστα αλλάζει σειρά ενώ ο χρήστης τη διαβάζει, ένα σήμα «φθηνότερο» μπορεί να μετακινηθεί, και ένα ξενοδοχείο που ήρθε από έναν προμηθευτή μπορεί αργότερα να πάρει φθηνότερο rate από άλλον.
Αν η διεπαφή σου είναι σελίδα αναζήτησης μπροστά σε άνθρωπο, το προοδευτικό μοντέλο είναι σχεδόν πάντα το σωστό — ο άνθρωπος περιηγείται, δεν τρέχει batch job, και μια σελίδα που φανερά δουλεύει κερδίζει μια σελίδα που σιωπηλά σκέφτεται. Αν ο καταναλωτής είναι άλλη μηχανή — ένα job σύγκρισης τιμών, ένα εταιρικό εργαλείο κρατήσεων που θέλει μία οριστική απάντηση — η αναμονή είναι συχνά απλούστερη και σωστή.
Ό,τι κι αν διαλέξεις, τρεις κανόνες κρατούν έναν προοδευτικό client λογικό:
- Κάθε παρτίδα φέρει μια κατάσταση ολοκλήρωσης για την αναζήτηση συνολικά, ώστε ο client να ξεχωρίζει το «δεν υπάρχουν άλλα αποτελέσματα ακόμη» από το «δεν θα υπάρξουν άλλα αποτελέσματα».
- Τα αποτελέσματα συγχωνεύονται με σταθερό κλειδί ξενοδοχείου στον server, δεν προσαρτώνται απλώς. Ο client δεν πρέπει ποτέ να χρειαστεί να καταλάβει μόνος του ότι δύο κάρτες είναι το ίδιο κτίριο.
- Η ταξινόμηση κατά τιμή είναι προσωρινή μέχρι να ολοκληρωθεί η αναζήτηση, και η διεπαφή το λέει. Οι χρήστες συγχωρούν μια λίστα που κατασταλάζει· δεν συγχωρούν μια ετικέτα «χαμηλότερη τιμή» που αποδεικνύεται λάθος.
Μοντελοποίηση δωματίων και rate plans χωρίς να καταρρεύσουν
Εδώ αποτυγχάνουν αθόρυβα οι περισσότερες ενσωματώσεις ξενοδοχείων, και η αποτυχία εμφανίζεται μήνες μετά ως αίτημα υποστήριξης, όχι ως bug report.
Το δελεαστικό μοντέλο είναι επίπεδο: ένα ξενοδοχείο έχει λίστα προσφορών, κάθε προσφορά έχει όνομα δωματίου και τιμή. Αποδίδεται ωραία στην οθόνη. Μετά ένας προμηθευτής επιστρέφει «Deluxe King» και «Deluxe Room, 1 King Bed» για προφανώς το ίδιο δωμάτιο, άλλος επιστρέφει το ίδιο όνομα για δύο πραγματικά διαφορετικά δωμάτια (ένα με θέα στην πόλη, ένα χωρίς), και ένας τρίτος επιστρέφει rate με τιμή ανά νύχτα ενώ όλοι οι άλλοι δίνουν τιμή ανά διαμονή. Μια επίπεδη λίστα δεν μπορεί να σου πει ποιο από αυτά βλέπεις. Απλώς τα δείχνει.
Ένα μοντέλο που αντέχει την επαφή με πραγματικούς προμηθευτές έχει τουλάχιστον τέσσερα επίπεδα και τα κρατά χωριστά:
| Επίπεδο | Τι περιέχει | Το λάθος που αποφεύγεις |
|---|---|---|
| Ξενοδοχείο | Το δικό σου σταθερό ID, αντιστοιχισμένο στον κωδικό κάθε προμηθευτή | Να χρησιμοποιείς το hotel ID ενός προμηθευτή ως πρωτεύον κλειδί |
| Δωμάτιο | Πληρότητα, διάταξη κρεβατιών, το κείμενο δωματίου του προμηθευτή αυτούσιο | Να «καθαρίζεις» ονόματα δωματίων μέχρι δύο διαφορετικά δωμάτια να γίνουν ένα |
| Rate plan | Διατροφή, επιστρεψιμότητα, τρόπος πληρωμής, ο προμηθευτής από τον οποίο ήρθε | Να θεωρείς το πρωινό ή την επιστρεψιμότητα μέρος του ονόματος του δωματίου |
| Τιμή | Σύνολο για τη διαμονή, νόμισμα, ποιοι φόροι και χρεώσεις περιλαμβάνονται και ποιοι πληρώνονται στο ξενοδοχείο | Να δείχνεις τιμή ανά νύχτα δίπλα σε τιμές ανά διαμονή ή να κρύβεις χρεώσεις που πληρώνονται κατά την άφιξη |
Μπορείς να διαφωνείς για το πού μπαίνουν τα όρια — κάποιες ομάδες βγάζουν την πληρότητα σε δικό της επίπεδο, κάτι λογικό από τη στιγμή που πουλάς κρατήσεις πολλών δωματίων. Αυτό που δεν μπορείς να κάνεις είναι να συγχωνεύσεις επίπεδα επειδή η διεπαφή δείχνει μόνο δύο από αυτά. Η διεπαφή μπορεί να «ισιώσει» τα δεδομένα τη στιγμή της απόδοσης. Τα δεδομένα δεν πρέπει.
Μία λεπτομέρεια αξίζει δική της πρόταση: κράτα την αρχική περιγραφή δωματίου του προμηθευτή δίπλα σε ό,τι κανονικοποιείς. Όταν ένας επισκέπτης φτάσει και του δοθεί άλλο δωμάτιο από αυτό στο voucher του, το πρώτο που θα ρωτήσει όποιος ασχοληθεί είναι τι ακριβώς έστειλε ο προμηθευτής.
Οι πολιτικές ακύρωσης είναι δεδομένα, όχι παράγραφος
Πολλοί προμηθευτές επιστρέφουν τους όρους ακύρωσης ως ελεύθερο κείμενο: «Δωρεάν ακύρωση έως 3 ημέρες πριν την άφιξη, μετά χρέωση 1 νύχτας.» Είναι πολύ δελεαστικό να δείξεις αυτό το string και να προχωρήσεις.
Μην το κάνεις. Το κείμενο δεν συγκρίνεται, δεν ταξινομείται, δεν φιλτράρεται και δεν επιβάλλεται. Ο χρήστης σου θέλει να φιλτράρει μόνο επιστρέψιμα rates. Το οικονομικό τμήμα θέλει να ξέρει ποιες κρατήσεις γίνονται μη επιστρέψιμες αύριο, ώστε το πρακτορείο να προλάβει τον πελάτη πριν περάσει η προθεσμία. Η ροή μετά την κράτηση πρέπει να πει στον πελάτη, τη στιγμή που πατά ακύρωση, ακριβώς πόσο θα χρεωθεί. Τίποτα από αυτά δεν λειτουργεί πάνω σε μια πρόταση.
Μοντελοποίησε κάθε πολιτική ως ταξινομημένη λίστα παραθύρων ποινής: από αυτή τη στιγμή, μέχρι εκείνη, η χρέωση είναι τόσο ποσό (ή τόσο ποσοστό της διαμονής, ή τόσες νύχτες). Τα όρια είναι timestamps με ζώνη ώρας — τη ζώνη ώρας του ξενοδοχείου, όχι του server σου και όχι του χρήστη — γιατί το «3 ημέρες πριν την άφιξη» σημαίνει διαφορετική στιγμή ανάλογα με το ποιανού μεσάνυχτα μετράς. Αποθήκευσε το αρχικό κείμενο του προμηθευτή δίπλα στη δομημένη εκδοχή, δείξε τη δομημένη, και αντιμετώπισε μια ασυμφωνία ανάμεσά τους ως κάτι που ερευνάς, όχι κάτι που κρύβεις.
Και ξαναέλεγξε την πολιτική τη στιγμή της κράτησης, όχι μόνο στην αναζήτηση. Οι πολιτικές αλλάζουν ανάμεσα στις δύο κλήσεις συχνότερα απ' όσο περιμένει κανείς.
Τι κοστίζει στην πράξη το λάθος
Μια αργή αναζήτηση σού κοστίζει μετατροπές — άσχημο, αλλά ορατό· κάποιος θα παραπονεθεί. Οι ακριβές αποτυχίες είναι οι αθόρυβες.
Ένα rate που εμφανίστηκε ως επιστρέψιμο ενώ ο προμηθευτής το θεωρεί μη επιστρέψιμο είναι διαφορά με πελάτη που έχει screenshot, και συνήθως το πρακτορείο πληρώνει την ποινή από την τσέπη του. Μια τιμή ανά νύχτα που εμφανίζεται ως σύνολο διαμονής πουλά δωμάτια κάτω από το κόστος μέχρι να το προσέξει κάποιος στο λογιστήριο. Ένα δωμάτιο που συγχωνεύτηκε με άλλο στέλνει μια τετραμελή οικογένεια σε δωμάτιο για δύο. Χρεώσεις πληρωτέες στο ξενοδοχείο που δεν εμφανίστηκαν ποτέ μετατρέπουν μια κριτική πέντε αστέρων σε chargeback. Καθένα από αυτά είναι απόφαση μοντελοποίησης που πάρθηκε στο πρώτο sprint, συνήθως με την ετικέτα «θα το καθαρίσουμε αργότερα».
Caching: τι μπορείς να κρατήσεις και τι όχι
Κάθε ομάδα που ενσωματώνει ξενοδοχειακό API κάποια στιγμή ρωτά αν μπορεί να κάνει cache τα αποτελέσματα για να γίνει η αναζήτηση γρηγορότερη και φθηνότερη. Η απάντηση είναι ναι, για κάποια πράγματα, και η γραμμή ανάμεσά τους μετρά περισσότερο από οποιονδήποτε αριθμό απόδοσης.
Το στατικό περιεχόμενο — ονόματα ξενοδοχείων, διευθύνσεις, συντεταγμένες, φωτογραφίες, λίστες παροχών, περιγραφές δωματίων — αλλάζει σπάνια και είναι ακριβώς αυτό που πρέπει να κάνεις cache, επιθετικά, στη δική σου αποθήκη. Έλεγξε τους όρους του προμηθευτή για το πώς επιτρέπεται να το αποθηκεύεις και να το εμφανίζεις· κάποιες άδειες το περιορίζουν. Το να το φέρνεις ζωντανά σε κάθε αναζήτηση είναι αργό χωρίς κανένα όφελος.
Οι ζωντανές τιμές και η διαθεσιμότητα είναι άλλη υπόθεση. Μια τιμή από cache είναι μια εικασία για το τι θα χρεώσει ο προμηθευτής, και οι προμηθευτές δεν τιμούν τις εικασίες σου. Βραχύβιο caching αποτελεσμάτων αναζήτησης μπορεί να είναι αποδεκτό για να δείξεις μια σελίδα — αρκεί κάθε διαδρομή κράτησης να επανατιμολογεί απέναντι στον προμηθευτή πριν πάρει χρήματα, και η διεπαφή να αντιμετωπίζει μια αλλαγμένη τιμή ως φυσιολογικό αποτέλεσμα, όχι ως σφάλμα. Κάποιοι προμηθευτές περιορίζουν επίσης πόσο συχνά μπορείς να ψάχνεις σε σχέση με το πόσο συχνά κλείνεις· ένα επιθετικό caching που τους κρύβει την πραγματική σου κίνηση δεν είναι παραθυράκι στο οποίο αξίζει να βασιστείς.
Αυτό που δεν πρέπει ποτέ να μπει σε cache είναι οτιδήποτε αντιπροσωπεύει δέσμευση: ένα κρατημένο price token, ένας κωδικός κράτησης, μια προσφορά ακύρωσης. Αυτά ανήκουν σε έναν χρήστη και μία στιγμή.
Πριν το πεις τελειωμένο
Ένας σύντομος έλεγχος, που αξίζει να τρέξεις πάνω στη δική σου ενσωμάτωση πριν σηκώσει πραγματικές κρατήσεις:
- Η αναζήτηση επιστρέφει κατάσταση ολοκλήρωσης, και ο client συμπεριφέρεται διαφορετικά πριν και μετά από αυτήν.
- Τα ξενοδοχεία έχουν κλειδί το δικό σου ID, με τον κωδικό κάθε προμηθευτή αντιστοιχισμένο σε αυτό.
- Δωμάτιο, rate plan και τιμή είναι ξεχωριστά αντικείμενα στα δεδομένα σου, ό,τι κι αν δείχνει η οθόνη.
- Κάθε τιμή λέει αν είναι ανά νύχτα ή ανά διαμονή, και τι πληρώνεται κατά την άφιξη.
- Οι πολιτικές ακύρωσης αποθηκεύονται ως χρονικά παράθυρα ποινής στη ζώνη ώρας του ξενοδοχείου, με το αρχικό κείμενο διατηρημένο.
- Η διαδρομή κράτησης επανατιμολογεί και ξαναδιαβάζει την πολιτική πριν χρεώσει οποιονδήποτε.
- Τίποτα που αντιπροσωπεύει δέσμευση δεν σερβίρεται ποτέ από cache.
Αν ζυγίζεις αν θα τα χτίσεις όλα αυτά απέναντι σε μεμονωμένους προμηθευτές ή αν θα ξεκινήσεις από μια πλατφόρμα που έχει ήδη συναντήσει αυτά τα προβλήματα, η συμβατική πλευρά μετρά όσο και ο κώδικας — το κείμενό μας για τα συμβόλαια με hotel consolidators και τις τιμές bedbank εξηγεί τι να ζητήσεις. Τα δικά μας API πτήσεων και ξενοδοχείων ανοίγουν μέσα από συζήτηση, όχι με self-serve κλειδί· αν αυτός είναι ο δρόμος που θέλεις να εξετάσεις, ξεκίνα τη συζήτηση στη σελίδα των travel APIs.
Το fan-out δεν φεύγει ποτέ. Ένας καλός client απλώς σταματά να προσποιείται ότι δεν υπάρχει.