API ketersediaan hotel: reka bentuk untuk pembekal yang perlahan

Tiketnya biasanya nampak tidak berbahaya. "Tambah carian hotel pada halaman tempahan — pembekal sudah beri kita API ketersediaan hotel, ada sandbox, sepatutnya satu sprint sahaja." Anda baca dokumentasinya, hantar permintaan untuk dua orang dewasa di Kuala Lumpur selama tiga malam, dan respons kembali. Kemudian anda hantar permintaan yang sama untuk bandar dengan lebih banyak hartanah, dan tiada apa-apa yang kembali untuk tempoh yang lama dan janggal. Apabila ia tiba, saiznya cukup besar untuk membuat parser JSON anda memikirkan semula pilihan hidupnya.
Pada saat itulah bentuk kerja berubah. Ketersediaan hotel bukan lookup. Ia adalah fan-out: satu soalan daripada pengguna anda menjadi banyak soalan kepada banyak pembekal, setiap satu menjawab mengikut kelajuan sendiri, dengan perbendaharaan kata sendiri, dengan tanggapan sendiri tentang apa itu "bilik". Klien yang anda bina mesti kekal berguna sepanjang fan-out itu masih belum selesai. Tulisan ini tentang mereka bentuk klien tersebut — untuk pembangun yang mahir REST dan JSON tetapi belum pernah terpaksa menerangkan kepada hotel mengapa kadar non-refundable seorang tetamu dipaparkan sebagai pembatalan percuma.
Mengapa API ketersediaan hotel lebih perlahan daripada endpoint biasa anda
Dari luar, carian penerbangan dan carian hotel kelihatan serupa: satu kueri keluar, pilihan berharga kembali. Di bawahnya, masalahnya tidak sama. Jika anda sudah membaca nota kami tentang apa yang sebenarnya terlibat dalam integrasi API tempahan penerbangan, anda tahu harga yang anda cari tidak semestinya harga yang anda tempah. Hotel menambah kesukaran kedua di atasnya: jumlah.
Satu bandar boleh mempunyai ratusan hartanah. Setiap hartanah menjual beberapa jenis bilik. Setiap jenis bilik dijual di bawah beberapa rate plan — dengan sarapan, tanpa sarapan, boleh dipulangkan, tidak boleh dipulangkan, kadar ahli, kadar pakej. Setiap rate plan mungkin datang daripada lebih satu sumber: bedbank, channel manager, kontrak langsung, pemborong yang anda tandatangani kerana allotment mereka di satu hotel lebih baik daripada orang lain. Darabkan semuanya dan carian "mudah" menjadi pokok yang besar, dihimpun daripada beberapa sumber yang tidak bersetuju tentang nama atau ID.
Jadi bahagian yang perlahan jarang sekali kod anda. Ia ialah pembekal paling perlahan yang anda pilih untuk ditunggu.
Hasil progresif atau jawapan penuh: pilih dengan sengaja
Ada dua cara jujur untuk memulangkan hasil carian hotel, dan kebanyakan integrasi berakhir di tengah-tengah yang tidak selesa.
Tunggu semuanya. Backend anda menyebarkan permintaan, menunggu setiap pembekal menjawab atau timeout, menggabung, membuang pendua, menyusun, dan memulangkan satu senarai lengkap. Hasilnya kemas: satu permintaan, satu respons, harga yang boleh dibandingkan kerana semuanya sudah di atas meja. Kosnya, pengguna anda merenung spinner selama mana pembekal paling perlahan anda ambil, setiap kali.
Hantar apa yang ada. Backend anda memulakan fan-out dan terus memulangkan search handle. Klien membuat polling pada handle itu, atau memegang stream terbuka, dan menerima hasil secara berkelompok apabila pembekal menjawab. Hotel pertama muncul dengan cepat. Kosnya ialah kerumitan di tempat lain: senarai menyusun semula ketika pengguna sedang membacanya, label "paling murah" boleh berpindah, dan hotel yang muncul daripada satu pembekal kemudiannya mungkin mendapat kadar lebih murah daripada pembekal lain.
Jika antara muka anda ialah halaman carian di hadapan manusia, progresif hampir selalu betul — orang itu sedang melayari, bukan menjalankan batch job, dan halaman yang jelas sedang bekerja lebih baik daripada halaman yang diam berfikir. Jika pengguna anda ialah mesin lain — job perbandingan kadar, alat tempahan korporat yang perlukan satu jawapan muktamad — menunggu sering kali lebih mudah dan betul.
Mana-mana yang anda pilih, tiga peraturan memastikan klien progresif kekal waras:
- Setiap kelompok membawa status penyiapan untuk keseluruhan carian, supaya klien tahu beza antara "belum ada hasil lagi" dan "tiada hasil lagi untuk selama-lamanya".
- Hasil digabungkan menggunakan kunci hotel yang stabil di pelayan, bukan ditambah di hujung. Klien tidak sepatutnya perlu meneka bahawa dua kad adalah bangunan yang sama.
- Susunan mengikut harga adalah sementara sehingga carian selesai, dan antara muka menyatakannya. Pengguna memaafkan senarai yang beransur tenang; mereka tidak memaafkan label "harga terendah" yang ternyata salah.
Memodelkan bilik dan rate plan supaya tidak runtuh
Di sinilah kebanyakan integrasi hotel gagal secara senyap, dan kegagalannya muncul berbulan-bulan kemudian sebagai tiket sokongan, bukan laporan pepijat.
Model yang menggoda ialah model rata: hotel ada senarai tawaran, setiap tawaran ada nama bilik dan harga. Ia dipaparkan dengan cantik. Kemudian satu pembekal memulangkan "Deluxe King" dan "Deluxe Room, 1 King Bed" untuk bilik yang jelas sama, pembekal lain memulangkan nama yang sama untuk dua bilik yang benar-benar berbeza (satu dengan pemandangan bandar, satu tidak), dan pembekal ketiga memulangkan kadar per malam sedangkan yang lain per penginapan. Senarai rata tidak dapat memberitahu anda yang mana satu sedang anda lihat. Ia hanya memaparkannya.
Model yang bertahan apabila berdepan pembekal sebenar mempunyai sekurang-kurangnya empat tahap, dan memisahkannya:
| Tahap | Apa yang disimpan | Kesilapan yang perlu dielakkan |
|---|---|---|
| Hotel | ID stabil anda sendiri, dipetakan kepada kod setiap pembekal | Menggunakan ID hotel pembekal sebagai primary key |
| Bilik | Penghunian, konfigurasi katil, teks bilik asal pembekal disimpan tanpa diubah | "Mengemas" nama bilik sehingga dua bilik berbeza bercantum menjadi satu |
| Rate plan | Board basis, refundability, jenis bayaran, pembekal asalnya | Menganggap sarapan atau refundability sebagai sebahagian nama bilik |
| Harga | Jumlah untuk keseluruhan penginapan, mata wang, cukai dan yuran yang termasuk serta yang dibayar di hotel | Memaparkan angka per malam di sebelah angka per penginapan, atau menyembunyikan yuran semasa daftar masuk |
Anda boleh tidak bersetuju di mana garisnya diletakkan — sesetengah pasukan memisahkan penghunian menjadi tahap sendiri, yang munasabah apabila anda menjual tempahan berbilang bilik. Apa yang tidak boleh ialah menggabungkan tahap hanya kerana antara muka memaparkan dua daripadanya. Antara muka boleh meratakan semasa render. Data tidak boleh.
Satu perincian wajar mendapat ayatnya sendiri: simpan perihalan bilik mentah daripada pembekal bersama versi yang dinormalkan. Apabila tetamu tiba dan diberi bilik yang berbeza daripada baucarnya, soalan pertama semua orang ialah apa sebenarnya yang dihantar pembekal.
Polisi pembatalan ialah data, bukan perenggan
Banyak pembekal memulangkan terma pembatalan sebagai teks bebas: "Pembatalan percuma sehingga 3 hari sebelum ketibaan, selepas itu penalti 1 malam." Sangat menggoda untuk memaparkan rentetan itu dan teruskan.
Jangan. Teks tidak boleh dibandingkan, disusun, ditapis atau dikuatkuasakan. Pengguna anda mahu menapis kadar yang boleh dipulangkan. Pasukan kewangan anda mahu tahu tempahan mana yang menjadi tidak boleh dipulangkan esok supaya agensi boleh menghubungi pelanggan sebelum tarikh akhir berlalu. Aliran selepas tempahan anda perlu memberitahu pelanggan, ketika mereka menekan butang batal, berapa tepat yang akan dikenakan. Semua itu tidak berfungsi di atas satu ayat.
Modelkan setiap polisi sebagai senarai tertib tetingkap penalti: dari detik ini, sehingga detik itu, caj adalah sebanyak ini (atau bahagian ini daripada penginapan, atau sekian malam). Sempadannya ialah timestamp dengan zon waktu — zon waktu hotel, bukan pelayan anda dan bukan pengguna — kerana "3 hari sebelum ketibaan" bermaksud detik berbeza bergantung tengah malam siapa yang anda kira. Simpan teks asal pembekal di sebelah versi berstruktur, paparkan versi berstruktur, dan anggap ketidaksepadanan antara keduanya sebagai sesuatu untuk disiasat, bukan disorok.
Dan semak semula polisi semasa tempahan, bukan hanya semasa carian. Polisi berubah antara dua panggilan itu lebih kerap daripada jangkaan sesiapa.
Apa sebenarnya kos sesuatu kesilapan
Carian yang perlahan menyebabkan anda kehilangan penukaran — buruk, tetapi kelihatan; seseorang akan mengadu. Kegagalan yang mahal ialah yang senyap.
Kadar yang dipaparkan boleh dipulangkan tetapi dianggap tidak boleh dipulangkan oleh pembekal ialah pertikaian dengan pelanggan yang memegang tangkapan skrin, dan biasanya agensi sendiri yang akhirnya membayar penalti. Harga per malam yang dipaparkan sebagai jumlah penginapan menjual bilik di bawah kos sehingga seseorang di bahagian perakaunan perasan. Bilik yang digabungkan dengan bilik lain menghantar keluarga empat orang ke bilik untuk dua orang. Yuran yang dibayar di hotel tetapi tidak pernah dipaparkan menukar ulasan lima bintang menjadi chargeback. Setiap satu ialah keputusan pemodelan yang dibuat dalam sprint pertama, biasanya dengan label "kita kemas kemudian".
Caching: apa yang boleh disimpan dan apa yang tidak
Setiap pasukan yang mengintegrasikan API hotel akhirnya bertanya sama ada hasil boleh di-cache supaya carian lebih pantas dan murah. Jawapannya ya, untuk sesetengah perkara, dan garis antaranya lebih penting daripada sebarang angka prestasi.
Kandungan statik — nama hotel, alamat, koordinat, foto, senarai kemudahan, perihalan bilik — jarang berubah dan itulah yang patut anda cache secara agresif dalam storan anda sendiri. Semak terma pembekal tentang cara anda boleh menyimpan dan memaparkannya; sesetengah lesen menghadkannya. Mengambilnya secara live pada setiap carian adalah perlahan tanpa faedah.
Kadar dan ketersediaan live perkara lain pula. Harga yang di-cache ialah tekaan tentang apa yang akan dicaj pembekal, dan pembekal tidak menghormati tekaan anda. Cache jangka pendek untuk hasil carian boleh diterima bagi memaparkan halaman — asalkan setiap laluan tempahan membuat harga semula dengan pembekal sebelum mengambil wang, dan antara muka menganggap harga yang berubah sebagai hasil biasa, bukan ralat. Sesetengah pembekal juga mengehadkan nisbah carian kepada tempahan; caching agresif yang menyembunyikan trafik sebenar anda daripada mereka bukan celah yang wajar diharapkan.
Apa yang tidak boleh sesekali di-cache ialah apa-apa yang mewakili komitmen: token harga yang ditahan, rujukan tempahan, sebut harga pembatalan. Semua itu milik seorang pengguna dan satu detik.
Sebelum anda menganggapnya selesai
Semakan ringkas yang wajar dijalankan pada integrasi anda sebelum ia mengendalikan tempahan sebenar:
- Carian memulangkan status penyiapan, dan klien berkelakuan berbeza sebelum dan selepasnya.
- Hotel dikunci dengan ID anda sendiri, dengan kod setiap pembekal dipetakan kepadanya.
- Bilik, rate plan dan harga ialah objek berasingan dalam data anda, apa pun yang dipaparkan skrin.
- Setiap harga menyatakan sama ada per malam atau per penginapan, dan apa yang dibayar semasa ketibaan.
- Polisi pembatalan disimpan sebagai tetingkap penalti bermasa dalam zon waktu hotel, dengan teks asal turut disimpan.
- Laluan tempahan membuat harga semula dan membaca semula polisi sebelum mengecaj sesiapa.
- Tiada apa-apa yang mewakili komitmen pernah disajikan daripada cache.
Jika anda sedang menimbang sama ada mahu membina semua ini terus dengan setiap pembekal atau bermula daripada platform yang sudah berdepan masalah-masalah ini, sisi kontrak sama penting dengan kod — tulisan kami tentang kontrak hotel consolidator dan kadar bedbank menerangkan apa yang perlu diminta. API penerbangan dan hotel kami dibuka melalui perbualan, bukan kunci layan diri; jika itu laluan yang ingin anda terokai, mulakan perbualan di halaman travel APIs.
Fan-out tidak pernah hilang. Klien yang baik cuma berhenti berpura-pura ia tiada.