Məzmuna keçin
Bloq

Otel mövcudluq API-si: ləng təchizatçılar üçün dizayn

Tekravel Redaksiyası
Süni intellektin köməyi ilə yazılıb

Tapşırıq adətən zərərsiz görünür: "Bron səhifəsinə otel axtarışı əlavə edək — təchizatçı bizə otel mövcudluq API-si verib, sandbox da var, bir sprintlik işdir." Sənədləri oxuyursunuz, Dubayda iki böyük üçün üç gecəlik sorğu göndərirsiniz və cavab gəlir. Sonra eyni sorğunu daha çox oteli olan bir şəhər üçün göndərirsiniz — və uzun, narahat bir müddət heç nə qayıtmır. Nəhayət gələndə isə elə həcmli bir sənəd olur ki, JSON parser-iniz belə həyat seçimləri barədə düşünməyə başlayır.

İşin forması məhz bu anda dəyişir. Otel mövcudluğu sadə lookup deyil. Bu, fan-out-dur: istifadəçinizin bir sualı çoxlu təchizatçıya gedən çoxlu suala çevrilir və hər biri öz sürətində, öz lüğətində, "nömrə" barədə öz təsəvvürü ilə cavab verir. Qurduğunuz klient bu fan-out hələ tamamlanmamışkən də faydalı qalmalıdır. Bu yazı həmin klientin dizaynı haqqındadır — REST və JSON-u yaxşı bilən, amma heç vaxt bir otelə qonağın non-refundable tarifinin niyə pulsuz ləğv ilə göstərildiyini izah etməli olmamış developer üçün.

Otel mövcudluq API-si niyə öyrəşdiyiniz endpoint-lərdən yavaşdır

Kənardan baxanda aviabilet axtarışı ilə otel axtarışı oxşardır: sorğu gedir, qiymətli variantlar qayıdır. Altda isə bunlar eyni problem deyil. Aviabilet bron API-si inteqrasiyasının əslində nələri əhatə etdiyi barədə qeydlərimizi oxumusunuzsa, bilirsiniz ki, axtarışda gördüyünüz qiymət həmişə bron etdiyiniz qiymət olmur. Otellər bunun üstünə ikinci çətinlik gətirir: həcm.

Bir şəhərdə yüzlərlə obyekt ola bilər. Hər obyekt bir neçə nömrə tipi satır. Hər nömrə tipi bir neçə rate plan (tarif planı) ilə satılır — səhər yeməyi ilə, onsuz, refundable, non-refundable, üzv tarifi, paket tarifi. Hər tarif planı isə birdən çox təchizatçıdan gələ bilər: bedbank, channel manager, birbaşa müqavilə, ya da sırf bir oteldəki allotment-i hamıdan yaxşı olduğu üçün müqavilə bağladığınız wholesaler. Bunları bir-birinə vurun — "sadə" axtarış adlar və ID-lər barədə razılaşmayan bir neçə mənbədən yığılmış böyük bir ağaca çevrilir.

Deməli, yavaş hissə nadir hallarda sizin kodunuz olur. Yavaş hissə gözləməyi özünüz seçdiyiniz ən ləng təchizatçıdır.

Mərhələli nəticələr, yoxsa tam cavab: şüurlu seçin

Otel axtarışı nəticələrini qaytarmağın iki dürüst yolu var və inteqrasiyaların çoxu sonda ikisinin arasında, heç kimi razı salmayan bir yerdə ilişib qalır.

Hamısını gözləyin. Backend sorğunu bütün təchizatçılara yayır, hər birinin cavabını və ya timeout-unu gözləyir, nəticələri birləşdirir, təkrarları silir, sıralayır və bir tam siyahı qaytarır. Nəticə təmizdir: bir sorğu, bir cavab və hamısı masada olduğu üçün müqayisə oluna bilən qiymətlər. Bədəli isə budur ki, istifadəçi hər dəfə ən yavaş təchizatçınız nə qədər ləngiyirsə, o qədər spinner-ə baxır.

Əlinizdə olanı göndərin. Backend fan-out-u başladır və dərhal search handle qaytarır. Klient bu handle-ı poll edir və ya stream-i açıq saxlayır, təchizatçılar cavab verdikcə nəticələri hissə-hissə alır. İlk otellər tez görünür. Bədəlini isə qalan hər yerdə mürəkkəblik kimi ödəyirsiniz: istifadəçi siyahını oxuyarkən sıra dəyişir, "ən ucuz" nişanı yerini dəyişə bilər, bir təchizatçıdan gəlmiş otel sonradan başqasından daha ucuz tarif ala bilər.

İnterfeysiniz insanın qarşısındakı axtarış səhifəsidirsə, mərhələli nəticələr demək olar ki, həmişə doğru seçimdir. Həmin adam batch job işlətmir, baxıb seçir — və işlədiyi açıq görünən səhifə səssizcə fikirləşən səhifədən yaxşıdır. İstehlakçınız başqa bir maşındırsa — tarifləri müqayisə edən job, yaxud bir qəti cavab tələb edən korporativ bron aləti — gözləmək çox vaxt həm sadə, həm də düzgündür.

Hansını seçsəniz də, üç qayda mərhələli klienti sağlam saxlayır:

  • Hər hissə bütövlükdə axtarışın tamamlanma vəziyyətini daşıyır ki, klient "hələlik başqa nəticə yoxdur" ilə "artıq heç vaxt olmayacaq" arasındakı fərqi bilsin.
  • Nəticələr serverdə sadəcə siyahının sonuna əlavə olunmur, sabit otel açarı ilə birləşdirilir. Klient iki kartın eyni bina olduğunu heç vaxt özü tapmalı olmamalıdır.
  • Qiymətə görə sıralama axtarış bitənə qədər müvəqqətidir və interfeys bunu açıq deyir. İstifadəçilər yavaş-yavaş yerinə oturan siyahını bağışlayır; sonradan yanlış çıxan "ən aşağı qiymət" etiketini bağışlamır.

Nömrələri və tarif planlarını dağılmayacaq şəkildə modelləşdirmək

Otel inteqrasiyalarının çoxu məhz burada səssizcə uğursuz olur və bu uğursuzluq aylar sonra bug report kimi yox, dəstək bileti kimi üzə çıxır.

Ən cəlbedici model düz siyahıdır: otelin təkliflər siyahısı var, hər təklifdə nömrənin adı və qiyməti. Ekranda gözəl görünür. Sonra bir təchizatçı açıq-aydın eyni nömrə üçün "Deluxe King" və "Deluxe Room, 1 King Bed" qaytarır, başqası həqiqətən fərqli iki nömrəyə eyni adı verir (biri şəhər mənzərəli, digəri mənzərəsiz), üçüncüsü isə qiyməti gecəlik olan bir tarif göndərir, halbuki qalanlarınınkı bütün qalış üçündür. Düz siyahı bunlardan hansına baxdığınızı deyə bilməz. Sadəcə göstərir.

Real təchizatçılarla qarşılaşıb sağ çıxan modeldə ən azı dörd səviyyə olur və o, bu səviyyələri bir-birindən ayrı saxlayır:

SəviyyəNə saxlayırQaçınmalı olduğunuz səhv
OtelSizin öz sabit ID-niz, hər təchizatçının koduna xəritələnmişTəchizatçının otel ID-sini primary key kimi istifadə etmək
NömrəTutum (occupancy), çarpayı konfiqurasiyası, təchizatçının öz nömrə mətni olduğu kimiNömrə adlarını o qədər "təmizləmək" ki, iki fərqli nömrə birinə qarışsın
Rate planQidalanma növü (board basis), geri qaytarılma şərti, ödəniş növü, hansı təchizatçıdan gəldiyiSəhər yeməyini və ya geri qaytarılmanı nömrə adının bir hissəsi saymaq
QiymətBütün qalış üçün cəm, valyuta, hansı vergi və rüsumların daxil olduğu və hansıların oteldə ödənildiyiGecəlik məbləği bütün qalış məbləğlərinin yanında göstərmək və ya gəlişdə ödənilən rüsumları gizlətmək

Xətlərin harada çəkildiyi ilə razılaşmaya bilərsiniz — bəzi komandalar tutumu ayrıca səviyyəyə çıxarır və çoxnömrəli bron satmağa başlayanda bu, ağlabatan addımdır. Etmək olmayan isə səviyyələri sırf interfeys onlardan ikisini göstərdiyi üçün birləşdirməkdir. İnterfeys render zamanı hər şeyi düzləşdirə bilər. Data isə yox.

Bir detal ayrıca cümləyə layiqdir: nəyi normallaşdırırsınızsa normallaşdırın, təchizatçının nömrə üçün göndərdiyi xam təsviri də yanında saxlayın. Qonaq gəlib vauçerdəkindən fərqli nömrə alanda hamının ilk sualı təchizatçının əslində nə göndərdiyi olacaq.

Ləğv qaydaları paraqraf deyil, datadır

Bir çox təchizatçı ləğv şərtlərini sərbəst mətn kimi qaytarır: "Gəlişdən 3 gün əvvələ qədər pulsuz ləğv, sonra 1 gecəlik cərimə." Bu sətri olduğu kimi göstərib keçmək çox cazibədardır.

Etməyin. Mətni nə müqayisə etmək, nə sıralamaq, nə filtrləmək, nə də icra etdirmək olur. İstifadəçiniz yalnız refundable tarifləri görmək istəyir. Maliyyə komandanız hansı bronların sabah non-refundable olacağını bilmək istəyir ki, agentlik son tarix keçməmiş müştəri ilə əlaqə saxlasın. Bron sonrası axın müştəriyə ləğv düyməsini basdığı anda ondan dəqiq nə qədər tutulacağını deməlidir. Bunların heç biri bir cümlənin üzərində işləmir.

Hər qaydanı cərimə pəncərələrinin (penalty windows) sıralı siyahısı kimi modelləşdirin: bu andan o ana qədər cərimə bu məbləğdir (və ya qalışın bu payı, ya da bu qədər gecə). Sərhədlər saat qurşağı ilə birlikdə timestamp-lardır — otelin saat qurşağı, nə serverinizin, nə də istifadəçinin — çünki "gəlişdən 3 gün əvvəl" kimin gecəyarısından saydığınızdan asılı olaraq fərqli an deməkdir. Təchizatçının orijinal mətnini strukturlaşdırılmış versiyanın yanında saxlayın, strukturlaşdırılmış versiyanı göstərin, aralarındakı uyğunsuzluğu isə gizlədiləcək şey yox, araşdırılacaq məsələ kimi qəbul edin.

Qaydanı yalnız axtarış zamanı yox, bron zamanı da yenidən yoxlayın. İki çağırış arasında qaydalar hər kəsin gözlədiyindən daha tez-tez dəyişir.

Səhvin real qiyməti

Yavaş axtarış sizə konversiya itkisinə başa gəlir — pisdir, amma görünür; kimsə mütləq şikayət edəcək. Bahalı uğursuzluqlar isə səssiz olanlardır.

Refundable göstərilən, amma təchizatçının non-refundable saydığı tarif əlində ekran görüntüsü olan müştəri ilə mübahisədir və cəriməni adətən agentlik özü ödəyir. Gecəlik qiymət bütün qalışın cəmi kimi göstərilsə, mühasibatlıqda kimsə fərqinə varana qədər nömrələr maya dəyərindən aşağı satılır. Başqa nömrə ilə birləşdirilmiş nömrə dörd nəfərlik ailəni iki nəfər üçün nəzərdə tutulmuş nömrəyə göndərir. Heç vaxt göstərilməmiş, oteldə ödənilən rüsumlar beşulduzlu rəyi chargeback-ə çevirir. Bunların hər biri ilk sprintdə, adətən "sonra təmizləyərik" adı altında verilmiş modelləşdirmə qərarıdır.

Keşləmə: nəyi saxlaya bilərsiniz, nəyi qətiyyən yox

Otel API-si inteqrasiya edən hər komanda gec-tez axtarışı daha sürətli və ucuz etmək üçün nəticələri keşləyə bilib-bilməyəcəyini soruşur. Cavab: bəli, bəzi şeylər üçün — və onların arasındakı xətt istənilən performans rəqəmindən daha vacibdir.

Statik kontent — otel adları, ünvanlar, koordinatlar, fotolar, imkanlar siyahısı, nömrə təsvirləri — nadir hallarda dəyişir və məhz öz anbarınızda cəsarətlə keşləməli olduğunuz şeydir. Onu necə saxlaya və göstərə biləcəyinizə dair təchizatçının şərtlərini yoxlayın; bəzi lisenziyalar bunu məhdudlaşdırır. Hər axtarışda onu canlı çəkmək heç bir fayda vermədən yavaşlıqdır.

Canlı tariflər və mövcudluq isə başqa məsələdir. Keşlənmiş qiymət təchizatçının nə qədər alacağı barədə təxmindir və təchizatçılar sizin təxminlərinizə əməl etmir. Səhifə göstərmək üçün axtarış nəticələrinin qısamüddətli keşlənməsi məqbul ola bilər — bir şərtlə ki, hər bron yolu pul almadan əvvəl təchizatçıdan qiyməti yenidən alsın və interfeys dəyişmiş qiyməti xəta yox, adi nəticə kimi qəbul etsin. Bəzi təchizatçılar bron sayına nisbətən nə qədər axtarış edə biləcəyinizi də məhdudlaşdırır; real trafikinizi onlardan gizlədən aqressiv keşləmə etibar ediləcək boşluq deyil.

Heç vaxt keşləməməli olduğunuz şey öhdəlik ifadə edən hər şeydir: saxlanılmış price token, bron referansı, ləğv qiyməti. Bunlar bir istifadəçiyə və bir ana aiddir.

"Hazırdır" deməzdən əvvəl

İnteqrasiyanız real bronlar daşımazdan əvvəl üzərində işlətməyə dəyən qısa yoxlama:

  • Axtarış tamamlanma vəziyyətini qaytarır və klient ondan əvvəl və sonra fərqli davranır.
  • Otellərin açarı sizin öz ID-nizdir, hər təchizatçının kodu ona xəritələnib.
  • Ekran nə göstərirsə göstərsin, nömrə, rate plan və qiymət datanızda ayrı obyektlərdir.
  • Hər qiymət gecəlik, yoxsa bütün qalış üçün olduğunu və gəlişdə nəyin ödəniləcəyini bildirir.
  • Ləğv qaydaları otelin saat qurşağında vaxta bağlı cərimə pəncərələri kimi saxlanılır, orijinal mətn də qorunur.
  • Bron yolu kimdənsə pul tutmazdan əvvəl qiyməti yenidən alır və qaydanı yenidən oxuyur.
  • Öhdəlik ifadə edən heç nə keşdən verilmir.

Bütün bunları ayrı-ayrı təchizatçılara qarşı özünüz qurmaqla bu problemlərlə artıq üzləşmiş platformadan başlamaq arasında seçim edirsinizsə, müqavilə tərəfi kod qədər vacibdir — otel konsolidatoru müqavilələri və bedbank tarifləri haqqında yazımız nə tələb etməli olduğunuzu izah edir. Öz aviabilet və otel API-lərimiz self-serve açarla deyil, söhbətlə açılır; bu yolu araşdırmaq istəyirsinizsə, travel APIs səhifəsində həmin söhbətə başlayın.

Fan-out heç vaxt yox olmur. Yaxşı klient sadəcə onun olmadığını iddia etməyi dayandırır.

Tekravel Redaksiyası

Səyahət texnologiyaları masası

Tekravel-in səyahət texnologiyaları masası sənaye üçün yazır: agentlik sahibləri, konsolidatorlar və onları inteqrasiya edən developerlər. Hər məqalə dərc olunmazdan əvvəl təsvir etdiyi platformada yoxlanılır.