İçeriğe geç
Blog

Otel müsaitlik API'si: yavaş tedarikçilere göre tasarım

Tekravel Editöryal
Yapay zekânın yardımıyla yazıldı

Görev genellikle masum bir cümleyle gelir: "Rezervasyon sayfasına otel aramasını ekleyin — tedarikçi bize bir otel müsaitlik API'si verdi, sandbox da var, bir sprint'lik iş." Dokümanı okursunuz, Antalya'da iki yetişkin için üç gecelik bir istek gönderirsiniz ve cevap gelir. Sonra aynı isteği çok daha fazla tesisi olan bir şehir için gönderirsiniz ve uzun, rahatsız edici bir süre boyunca hiçbir şey gelmez. Geldiğinde ise JSON ayrıştırıcınızı hayatını sorgulatacak büyüklükte bir belgedir.

İşin şekli tam o anda değişir. Otel müsaitliği bir sorgu değildir; bir fan-out'tur. Kullanıcının tek sorusu, birçok tedarikçiye giden birçok soruya dönüşür ve her biri kendi hızında, kendi kelime dağarcığıyla, "oda" kavramının kendi tanımıyla cevap verir. Kurduğunuz istemci, bu dağılım henüz tamamlanmamışken de işe yarar kalmak zorundadır. Bu yazı o istemciyi tasarlamakla ilgili; REST ve JSON'u iyi bilen ama bir otele, misafirin iade edilemez fiyatının neden ücretsiz iptal olarak gösterildiğini hiç açıklamak zorunda kalmamış bir geliştirici için yazıldı.

Otel müsaitlik API'si neden alıştığınız uç noktalardan yavaştır

Uçuş araması ile otel araması dışarıdan benzer görünür: bir sorgu çıkar, fiyatlı seçenekler döner. İçeride ise aynı problem değildir. Uçuş rezervasyon API entegrasyonunun gerçekte neler gerektirdiğine dair notlarımızı okuduysanız, aradığınız fiyatın her zaman rezerve ettiğiniz fiyat olmadığını zaten biliyorsunuz. Oteller bunun üstüne ikinci bir zorluk ekler: hacim.

Tek bir şehirde yüzlerce tesis olabilir. Her tesis birkaç oda tipi satar. Her oda tipi birkaç fiyat planıyla satılır — kahvaltılı, kahvaltısız, iade edilebilir, iade edilemez, üye fiyatı, paket fiyatı. Her fiyat planı birden fazla tedarikçiden gelebilir: bir bedbank, bir kanal yöneticisi, doğrudan bir kontrat ya da bir oteldeki allotment'ı herkesinkinden iyi olduğu için anlaştığınız bir toptancı. Bunları çarpın; "basit" bir arama, isimlerde ve kimliklerde anlaşamayan birkaç kaynaktan toplanmış büyük bir ağaçtır.

Yani yavaş olan nadiren sizin kodunuzdur. Beklemeyi seçtiğiniz en yavaş tedarikçidir.

Kademeli sonuçlar mı, tam cevap mı: bilinçli seçin

Otel arama sonuçlarını döndürmenin iki dürüst yolu vardır ve çoğu entegrasyon ikisinin arasında mutsuz bir yerde kalır.

Herkesi bekleyin. Arka uç isteği dağıtır, her tedarikçinin cevap vermesini ya da zaman aşımına uğramasını bekler, birleştirir, tekrarları temizler, sıralar ve tek bir tam liste döndürür. Sonuç temizdir: tek istek, tek cevap ve hepsi masada olduğu için karşılaştırılabilir fiyatlar. Bedeli şudur: kullanıcı her seferinde en yavaş tedarikçi ne kadar sürüyorsa o kadar dönen simgeye bakar.

Geleni akıtın. Arka uç dağıtımı başlatır ve hemen bir arama tanıtıcısı (handle) döndürür. İstemci bu tanıtıcıyı yoklar ya da bir akışı açık tutar ve tedarikçiler cevap verdikçe sonuçları partiler halinde alır. İlk oteller hızla görünür. Bedeli başka her yerdeki karmaşıklıktır: kullanıcı okurken liste yeniden sıralanır, "en ucuz" rozeti yer değiştirebilir, bir tedarikçiden gelen otel sonradan başka bir tedarikçiden daha ucuz bir fiyat alabilir.

Arayüzünüz bir insanın önündeki arama sayfasıysa, kademeli yaklaşım neredeyse her zaman doğrudur — kişi gezinmektedir, toplu iş çalıştırmıyordur ve görünür şekilde çalışan bir sayfa sessizce düşünen bir sayfadan iyidir. Tüketiciniz başka bir makineyse — bir fiyat karşılaştırma işi, tek ve kesin bir cevaba ihtiyaç duyan kurumsal bir rezervasyon aracı — beklemek çoğu zaman daha basit ve doğrudur.

Hangisini seçerseniz seçin, üç kural kademeli bir istemciyi aklı başında tutar:

  • Her parti, aramanın bütünü için bir tamamlanma durumu taşır; böylece istemci "henüz başka sonuç yok" ile "artık hiç sonuç gelmeyecek" arasındaki farkı bilir.
  • Sonuçlar sunucuda sabit bir otel anahtarıyla birleştirilir, sona eklenmez. İstemci iki kartın aynı bina olduğunu kendisi çıkarmak zorunda kalmamalıdır.
  • Fiyata göre sıralama arama tamamlanana kadar geçicidir ve arayüz bunu söyler. Kullanıcılar yerine oturan bir listeyi affeder; yanlış çıkan bir "en düşük fiyat" etiketini affetmez.

Odaları ve fiyat planlarını çökmeyecek şekilde modellemek

Otel entegrasyonlarının çoğu burada sessizce başarısız olur ve bu başarısızlık aylar sonra bir hata raporu olarak değil, bir destek talebi olarak ortaya çıkar.

Cazip model düzdür: bir otelin bir teklif listesi vardır, her teklifin bir oda adı ve fiyatı vardır. Ekranda güzel görünür. Sonra bir tedarikçi açıkça aynı oda için "Deluxe King" ve "Deluxe Room, 1 King Bed" döndürür, bir başkası gerçekten farklı iki oda için (biri şehir manzaralı, diğeri değil) aynı adı döndürür, üçüncüsü ise herkes konaklama başına fiyat verirken gecelik fiyat döndürür. Düz bir liste hangisine baktığınızı söyleyemez. Sadece gösterir.

Gerçek tedarikçilerle temasa dayanan bir modelin en az dört seviyesi vardır ve bunları ayrı tutar:

SeviyeNe tutarKaçınılacak hata
OtelKendi sabit kimliğiniz, her tedarikçinin koduna eşlenmişTedarikçinin otel kimliğini birincil anahtar olarak kullanmak
OdaKapasite, yatak düzeni, tedarikçinin kendi oda metni olduğu gibi saklanmışOda adlarını iki farklı oda tek odaya dönüşene kadar "temizlemek"
Fiyat planıPansiyon tipi, iade edilebilirlik, ödeme şekli, geldiği tedarikçiKahvaltıyı ya da iade edilebilirliği oda adının parçası saymak
FiyatKonaklamanın toplamı, para birimi, içindeki vergi ve ücretler ile otelde ödenecek olanlarKonaklama başına fiyatların yanında gecelik fiyat göstermek ya da varışta ödenen ücretleri gizlemek

Çizgilerin nereye düştüğüne itiraz edebilirsiniz — bazı ekipler kapasiteyi kendi seviyesine ayırır; çok odalı rezervasyon sattığınızda bu mantıklıdır. Yapamayacağınız şey, arayüz yalnızca ikisini gösteriyor diye seviyeleri birleştirmektir. Arayüz çizim anında düzleştirebilir. Veri düzleşmemelidir.

Bir ayrıntı kendi cümlesini hak ediyor: normalleştirdiğiniz her şeyin yanında tedarikçinin ham oda açıklamasını saklayın. Misafir gelip voucher'ındakinden farklı bir oda aldığında herkesin soracağı ilk şey, tedarikçinin gerçekte ne gönderdiğidir.

İptal politikaları veridir, paragraf değil

Birçok tedarikçi iptal koşullarını serbest metin olarak döndürür: "Varıştan 3 gün öncesine kadar ücretsiz iptal, sonrasında 1 gece ceza." Bu metni gösterip geçmek çok caziptir.

Yapmayın. Metin karşılaştırılamaz, sıralanamaz, filtrelenemez ve uygulanamaz. Kullanıcınız iade edilebilir fiyatlara filtrelemek ister. Finans ekibiniz hangi rezervasyonların yarın iade edilemez hale geleceğini bilmek ister ki acente süre dolmadan müşterinin peşine düşebilsin. Rezervasyon sonrası akışınız, müşteri iptal düğmesine bastığı anda tam olarak ne kadar ücret alınacağını söylemek zorundadır. Bunların hiçbiri bir cümle üzerinde çalışmaz.

Her politikayı sıralı bir ceza pencereleri listesi olarak modelleyin: şu andan şu ana kadar ceza şu tutardır (ya da konaklamanın şu payı, ya da şu kadar gece). Sınırlar saat dilimi taşıyan zaman damgalarıdır — sunucunuzun ya da kullanıcının değil, otelin saat dilimi — çünkü "varıştan 3 gün önce" kimin gece yarısından saydığınıza göre farklı bir anı ifade eder. Tedarikçinin orijinal metnini yapılandırılmış sürümün yanında saklayın, yapılandırılmış sürümü gösterin ve ikisi arasındaki uyumsuzluğu saklanacak bir şey değil, incelenecek bir şey olarak ele alın.

Ve politikayı yalnızca arama anında değil, rezervasyon anında da yeniden kontrol edin. Politikalar iki çağrı arasında herkesin beklediğinden sık değişir.

Yanlış yapmanın gerçek maliyeti

Yavaş bir arama size dönüşüm kaybettirir; kötüdür ama görünürdür — biri şikâyet eder. Pahalı hatalar sessiz olanlardır.

İade edilebilir gösterilen ama tedarikçinin iade edilemez saydığı bir fiyat, elinde ekran görüntüsü olan bir müşteriyle anlaşmazlık demektir ve cezayı çoğunlukla acentenin kendisi öder. Konaklama toplamı gibi gösterilen gecelik fiyat, muhasebeden biri fark edene kadar odaları maliyetin altında satar. Farklı bir odayla birleştirilmiş oda, dört kişilik bir aileyi iki kişilik bir odaya gönderir. Hiç gösterilmemiş, otelde ödenen ücretler beş yıldızlı bir yorumu ters ibraza (chargeback) dönüştürür. Bunların her biri ilk sprint'te, genellikle "sonra toparlarız" etiketiyle alınmış bir modelleme kararıdır.

Önbellek: neyi tutabilirsiniz, neyi tutmamalısınız

Bir otel API'si entegre eden her ekip sonunda aramayı hızlandırmak ve ucuzlatmak için sonuçları önbelleğe alıp alamayacağını sorar. Cevap: bazı şeyler için evet ve aradaki çizgi herhangi bir performans rakamından daha önemlidir.

Statik içerik — otel adları, adresler, koordinatlar, fotoğraflar, olanak listeleri, oda açıklamaları — nadiren değişir ve tam da kendi deponuzda agresif biçimde önbelleğe almanız gereken şeydir. Nasıl saklayıp gösterebileceğinize dair tedarikçi koşullarını kontrol edin; bazı lisanslar bunu kısıtlar. Her aramada canlı çekmek, hiçbir fayda sağlamadan yavaştır.

Canlı fiyatlar ve müsaitlik ise başka bir konudur. Önbellekteki fiyat, tedarikçinin ne talep edeceğine dair bir tahmindir ve tedarikçiler tahminlerinize uymaz. Arama sonuçlarının kısa süreli önbelleğe alınması bir sayfayı göstermek için kabul edilebilir — yeter ki her rezervasyon yolu para almadan önce tedarikçide yeniden fiyatlasın ve arayüz değişen fiyatı hata değil, normal bir sonuç olarak ele alsın. Bazı tedarikçiler ayrıca rezervasyona oranla ne sıklıkta arama yapabileceğinizi sınırlar; gerçek trafiğinizi onlardan gizleyen agresif önbellek, güvenilecek bir açık değildir.

Asla önbelleğe almamanız gereken şey, bir taahhüdü temsil eden her şeydir: tutulmuş bir fiyat token'ı, bir rezervasyon referansı, bir iptal teklifi. Bunlar tek bir kullanıcıya ve tek bir ana aittir.

Bitti demeden önce

Gerçek rezervasyon taşımadan önce kendi entegrasyonunuza uygulamaya değer kısa bir kontrol listesi:

  • Arama bir tamamlanma durumu döndürür ve istemci öncesinde ve sonrasında farklı davranır.
  • Oteller kendi kimliğinizle anahtarlanır, her tedarikçinin kodu buna eşlenir.
  • Ekranda ne görünürse görünsün, oda, fiyat planı ve fiyat verinizde ayrı nesnelerdir.
  • Her fiyat gecelik mi konaklama başına mı olduğunu ve varışta neyin ödeneceğini söyler.
  • İptal politikaları, otelin saat diliminde zamanlı ceza pencereleri olarak saklanır; orijinal metin korunur.
  • Rezervasyon yolu kimseden ücret almadan önce yeniden fiyatlar ve politikayı yeniden okur.
  • Taahhüt temsil eden hiçbir şey önbellekten sunulmaz.

Tüm bunları tek tek tedarikçilere karşı mı kuracağınızı, yoksa bu sorunlarla zaten karşılaşmış bir platformdan mı başlayacağınızı tartıyorsanız, kontrat tarafı kod kadar önemlidir — otel konsolidatör kontratları ve bedbank fiyatları yazımız neyi istemeniz gerektiğini anlatıyor. Kendi uçuş ve otel API'lerimiz self-servis bir anahtarla değil, bir görüşmeyle açılır; keşfetmek istediğiniz yol buysa o görüşmeyi seyahat API'leri sayfasından başlatın.

Fan-out hiçbir zaman ortadan kalkmaz. İyi bir istemci yalnızca orada değilmiş gibi davranmayı bırakır.

Tekravel Editöryal

Seyahat teknolojisi masası

Tekravel seyahat teknolojisi masası sektör için yazar: acente sahipleri, konsolidatörler ve onları entegre eden geliştiriciler. Her yazı, yayımlanmadan önce anlattığı platform üzerinde doğrulanır.