ホテル空室API:遅いサプライヤーを前提にしたクライアント設計

チケットはたいてい無害に見える。「予約ページにホテル検索を追加してほしい。サプライヤーからホテル空室APIをもらっていて、sandboxもある。1スプリントで終わるはず」。ドキュメントを読み、大阪で大人2名・3泊の条件でリクエストを送ると、レスポンスが返ってくる。次に施設数がずっと多い都市で同じリクエストを送ると、気まずいほど長いあいだ何も返ってこない。ようやく届いたのは、JSONパーサーが自分の人生を見つめ直しそうなほど巨大なドキュメントだ。
この瞬間に仕事の形が変わる。ホテルの空室確認は単なる参照ではない。fan-outだ。ユーザーの1つの問いが、複数のサプライヤーへの複数の問いになり、各社がそれぞれの速度で、それぞれの用語で、「部屋」とは何かについてそれぞれの解釈で答えてくる。作るべきクライアントは、そのfan-outがまだ解決しきっていない間ずっと役に立たなければならない。本稿はそのクライアント設計の話だ。RESTとJSONには慣れているが、ゲストの返金不可料金がなぜ「無料キャンセル」と表示されたのかをホテルに説明した経験はない開発者に向けて書いている。
ホテル空室APIが見慣れたエンドポイントより遅い理由
外から見れば、航空券検索とホテル検索は似ている。クエリが出て、価格付きの選択肢が返る。だが中身は同じ問題ではない。航空券予約APIの連携に実際何が必要かをまとめた記事を読んだなら、検索した価格が必ずしも予約できる価格ではないことはご存じだろう。ホテルはそこに2つ目の難しさを重ねる。量だ。
1つの都市に数百の施設がありうる。施設ごとに客室タイプが複数あり、客室タイプごとにrate planが複数ある。朝食付き、素泊まり、返金可、返金不可、会員料金、パッケージ料金。そして1つのrate planが複数の仕入れ先から来ることもある。bedbank、channel manager、直接契約、ある1軒のホテルでallotmentが誰よりも良かったから契約した卸。これを全部掛け合わせると、「単純な」検索は名前もIDも一致しない複数の仕入れ先から組み立てた巨大な木になる。
だから遅いのは、たいてい自分のコードではない。待つと決めたサプライヤーのうち、いちばん遅い1社だ。
段階的な結果か、完全な回答か:意図して選ぶ
ホテル検索の結果を返す誠実な方法は2つあり、多くの連携はその中間の居心地の悪い場所に落ち着いてしまう。
すべてを待つ。バックエンドがリクエストを広げ、全サプライヤーの応答かタイムアウトを待ち、マージし、重複を除き、並べ替え、完全なリストを1つ返す。結果はきれいだ。リクエスト1回、レスポンス1回、すべての価格が出そろっているので比較もできる。代償は、毎回いちばん遅いサプライヤーがかかる時間だけ、ユーザーがスピナーを見つめ続けることだ。
あるものから送る。バックエンドがfan-outを開始し、即座にsearch handleを返す。クライアントはそのhandleをポーリングするか、ストリームを開いたまま、サプライヤーが応答するたびに結果をバッチで受け取る。最初のホテルはすぐに表示される。代償は、ほかのあらゆる場所で増える複雑さだ。ユーザーが読んでいる最中にリストの順番が変わり、「最安値」のバッジが移動し、あるサプライヤー経由で出てきたホテルに、後から別のサプライヤーがもっと安い料金を出すこともある。
インターフェースが人間の前にある検索ページなら、段階的な表示がほぼ常に正解だ。その人は眺めているのであってバッチ処理を回しているわけではないし、目に見えて動いているページは黙って考え込むページより良い。消費者が別の機械なら、たとえば料金比較ジョブや、確定した答えが1つ必要な法人出張予約ツールなら、待つほうが単純で正しいことが多い。
どちらを選ぶにしても、段階的なクライアントを正気に保つルールは3つある。
- 各バッチは検索全体の完了状態を持ち、クライアントが「まだ次の結果はない」と「もう結果は来ない」を区別できるようにする。
- 結果はサーバー側で安定したホテルキーでマージし、末尾に追加するだけにしない。2枚のカードが同じ建物だとクライアントが自力で突き止める必要があってはならない。
- 価格順の並びは検索完了までは暫定であり、画面にもそう示す。ユーザーは落ち着いていくリストは許すが、間違いだとわかった「最安値」表示は許さない。
崩れない客室とrate planのモデリング
多くのホテル連携が静かに失敗するのはここで、その失敗は数か月後、バグ報告ではなくサポートチケットとして現れる。
魅力的なのはフラットなモデルだ。ホテルにオファーのリストがあり、各オファーに客室名と価格がある。画面映えもする。ところが、あるサプライヤーは明らかに同じ部屋を「Deluxe King」と「Deluxe Room, 1 King Bed」として返し、別のサプライヤーは本当に違う2部屋(シティビューとそうでない部屋)に同じ名前を付け、3社目は他社が滞在総額を返すなかで1泊料金を返してくる。フラットなリストは、いま見ているのがどのケースなのかを教えてくれない。ただ表示するだけだ。
実際のサプライヤーとぶつかっても持ちこたえるモデルには少なくとも4つの階層があり、それらを分けたままにしておく。
| 階層 | 持つもの | 避けるべき失敗 |
|---|---|---|
| ホテル | 自社の安定したID、各サプライヤーのコードとのマッピング | サプライヤーのホテルIDを主キーにする |
| 客室 | 定員、ベッド構成、サプライヤーの客室テキスト原文そのまま | 客室名を「整理」しすぎて、別々の2部屋を1つにまとめてしまう |
| Rate plan | Board basis、返金可否、支払い方法、どのサプライヤーから来たか | 朝食や返金可否を客室名の一部として扱う |
| 価格 | 滞在全体の総額、通貨、含まれる税・手数料と現地払いの分 | 1泊料金を滞在総額の横に並べる、チェックイン時に払う手数料を隠す |
どこで線を引くかに異論はあっていい。定員を独立した階層に分けるチームもあり、複数室予約を売るなら妥当な判断だ。してはいけないのは、画面が2階層しか見せないからといって階層を統合することだ。画面はレンダリング時にフラットにしてかまわない。データはだめだ。
ひとつだけ独立した一文に値する細部がある。正規化した値が何であれ、その横にサプライヤーの客室説明の原文を残しておくこと。ゲストが到着してバウチャーと違う部屋を割り当てられたとき、誰もが最初に尋ねるのは、サプライヤーが実際に何を送ってきたかだ。
キャンセル規定は文章ではなくデータ
多くのサプライヤーはキャンセル条件を自由記述のテキストで返す。「到着3日前まで無料キャンセル、それ以降は1泊分の違約金」。この文字列をそのまま表示して次へ進みたくなる。
やめておこう。テキストは比較も、並べ替えも、絞り込みも、強制もできない。ユーザーは返金可能な料金だけに絞り込みたい。経理チームは、明日から返金不可になる予約がどれかを知りたい。そうすれば旅行会社が期限前に顧客へ連絡できる。予約後のフローは、顧客がキャンセルボタンを押したその瞬間に、正確にいくら請求されるかを伝えなければならない。どれも1つの文の上では動かない。
各規定を、違約金ウィンドウの順序付きリストとしてモデリングする。この時点からあの時点までは、違約金はこの金額(あるいは滞在のこの割合、あるいはこの泊数)。境界はタイムゾーン付きのタイムスタンプで、そのタイムゾーンはサーバーでもユーザーでもなくホテルのものだ。「到着3日前」は、誰の真夜中を基準に数えるかで別の瞬間になるからだ。サプライヤーの原文は構造化版の横に保存し、表示には構造化版を使い、両者の食い違いは隠すものではなく調べるものとして扱う。
そして規定は検索時だけでなく予約時にも再確認する。2つの呼び出しのあいだに規定が変わることは、誰が予想するよりも多い。
間違えたとき実際にかかるコスト
検索が遅いとコンバージョンを失う。悪いことだが目に見えるし、誰かが文句を言う。高くつくのは静かな失敗だ。
返金可と表示したのにサプライヤーは返金不可として扱う料金は、スクリーンショットを持った顧客との紛争になり、違約金はたいてい旅行会社がかぶる。1泊料金を滞在総額として表示すれば、経理の誰かが気づくまで原価割れで客室を売り続ける。別の客室と統合された客室は、4人家族を2人部屋に送り込む。一度も表示されなかった現地払い手数料は、星5つのレビューをchargebackに変える。どれも最初のスプリントで「あとで整理しよう」というラベルとともに下されたモデリング上の判断だ。
キャッシュ:保持してよいもの、決してしてはいけないもの
ホテルAPIを連携するチームは、いずれ検索を速く安くするために結果をキャッシュしてよいかと尋ねる。答えは「一部はよい」で、その境界線はどんな性能値よりも重要だ。
静的コンテンツ、つまりホテル名、住所、座標、写真、設備リスト、客室説明はめったに変わらず、まさに自社ストアに積極的にキャッシュすべきものだ。保存と表示の方法についてはサプライヤーの規約を確認すること。制限のあるライセンスもある。検索のたびにライブで取得するのは、利点なしに遅いだけだ。
ライブの料金と空室は話が別だ。キャッシュした価格は、サプライヤーがいくら請求するかについての推測にすぎず、サプライヤーはその推測を尊重しない。ページ表示のために検索結果を短時間キャッシュするのは許容できる場合がある。ただし、すべての予約経路が代金を受け取る前にサプライヤーへ再見積もりを行い、画面が価格変動をエラーではなく通常の結果として扱うならの話だ。検索数と予約数の比率を制限するサプライヤーもある。実際のトラフィックを隠すほど強引なキャッシュは、頼れる抜け道ではない。
決してキャッシュしてはいけないのは、約束を表すものすべてだ。確保した価格トークン、予約番号、キャンセル違約金の見積もり。これらは1人のユーザーと1つの瞬間に属している。
完成と言う前に
実際の予約を扱う前に、自分の連携に対して走らせておきたい短いチェックリスト。
- 検索が完了状態を返し、クライアントはその前後で異なる振る舞いをする。
- ホテルは自社IDをキーにしており、各サプライヤーのコードがそこにマッピングされている。
- 画面に何が表示されていても、データ上の客室・rate plan・価格は別々のオブジェクトだ。
- すべての価格が1泊分か滞在総額か、到着時に何を払うかを明示している。
- キャンセル規定はホテルのタイムゾーンで時間区切りの違約金ウィンドウとして保存され、原文も残っている。
- 予約経路は誰かに請求する前に、価格と規定を再確認する。
- 約束を表すものは、何一つキャッシュから返さない。
これをすべてサプライヤーごとに自前で作るか、こうした問題をすでに経験したプラットフォームから始めるかを比べているなら、コードと同じくらい契約面も重要だ。ホテル卸の契約とbedbank料金の記事に、何を求めるべきかをまとめている。私たちの航空・ホテルAPIはセルフサービスのキーではなく、対話を通じて開放している。その道を検討したいなら、travel APIsのページから相談を始めてほしい。
fan-outが消えることはない。良いクライアントは、それが存在しないふりをやめるだけだ。