호텔 가용성 API: 느린 공급사를 전제로 한 클라이언트 설계

티켓은 대개 순해 보입니다. "예약 페이지에 호텔 검색 추가해 주세요. 공급사가 호텔 가용성 API를 줬고 sandbox도 있으니 한 스프린트면 될 겁니다." 문서를 읽고, 제주에서 성인 두 명이 세 박 묵는 조건으로 요청을 보내면 응답이 옵니다. 그런데 숙소가 훨씬 많은 도시로 같은 요청을 보내면 한참 동안, 불편할 만큼 오래 아무것도 돌아오지 않습니다. 마침내 돌아온 응답은 JSON 파서가 자기 인생을 돌아보게 만들 만큼 거대합니다.
그 순간 일의 성격이 바뀝니다. 호텔 가용성은 단순 조회가 아닙니다. fan-out입니다. 사용자의 질문 하나가 여러 공급사에 던지는 여러 질문이 되고, 각 공급사는 자기 속도로, 자기 용어로, "객실"이 무엇인지에 대한 자기만의 정의로 답합니다. 여러분이 만드는 클라이언트는 그 fan-out이 아직 끝나지 않은 내내 쓸모가 있어야 합니다. 이 글은 그런 클라이언트를 설계하는 이야기입니다. REST와 JSON은 익숙하지만, 손님의 환불 불가 요금이 왜 "무료 취소"로 표시됐는지 호텔에 해명해 본 적은 없는 개발자를 위해 썼습니다.
호텔 가용성 API가 익숙한 엔드포인트보다 느린 이유
밖에서 보면 항공 검색과 호텔 검색은 비슷합니다. 쿼리가 나가고, 가격이 붙은 선택지가 돌아옵니다. 하지만 속은 같은 문제가 아닙니다. 항공 예약 API 연동에 실제로 무엇이 필요한지 정리한 글을 읽으셨다면, 검색한 가격이 늘 예약되는 가격은 아니라는 점을 이미 아실 겁니다. 호텔은 여기에 두 번째 어려움을 얹습니다. 바로 물량입니다.
도시 하나에 숙소가 수백 곳 있을 수 있습니다. 숙소마다 객실 타입이 여러 개이고, 객실 타입마다 rate plan이 여러 개입니다. 조식 포함, 조식 불포함, 환불 가능, 환불 불가, 회원 요금, 패키지 요금. 그리고 rate plan 하나가 여러 출처에서 올 수 있습니다. bedbank, channel manager, 직계약, 그리고 특정 호텔의 allotment가 누구보다 좋아서 계약한 도매사까지. 이걸 모두 곱하면 "단순한" 검색은 이름도 ID도 서로 맞지 않는 여러 출처를 이어 붙인 거대한 트리가 됩니다.
그러니 느린 쪽은 거의 여러분의 코드가 아닙니다. 기다리기로 한 공급사 중 가장 느린 곳입니다.
점진적 결과냐, 완전한 응답이냐: 의도를 갖고 고르기
호텔 검색 결과를 돌려주는 정직한 방법은 두 가지이고, 대부분의 연동은 그 사이 어딘가 어정쩡한 곳에 머뭅니다.
전부 기다리기. 백엔드가 요청을 퍼뜨리고, 모든 공급사가 응답하거나 타임아웃될 때까지 기다린 뒤, 병합하고 중복을 제거하고 정렬해서 완전한 목록 하나를 돌려줍니다. 결과는 깔끔합니다. 요청 하나, 응답 하나, 모든 가격이 한자리에 있으니 비교도 됩니다. 대가는 사용자가 매번 가장 느린 공급사가 걸리는 시간만큼 스피너를 쳐다봐야 한다는 점입니다.
있는 것부터 보내기. 백엔드가 fan-out을 시작하고 즉시 search handle을 돌려줍니다. 클라이언트는 그 handle을 폴링하거나 스트림을 열어 둔 채, 공급사가 응답하는 대로 결과를 묶음 단위로 받습니다. 첫 호텔들이 빨리 보입니다. 대가는 나머지 모든 곳의 복잡도입니다. 사용자가 읽는 도중에 목록 순서가 바뀌고, "최저가" 배지가 옮겨 가고, 한 공급사에서 먼저 나온 호텔이 나중에 다른 공급사에서 더 싼 요금을 받기도 합니다.
인터페이스가 사람 앞에 놓인 검색 페이지라면 점진적 방식이 거의 항상 맞습니다. 그 사람은 둘러보는 중이지 배치 작업을 돌리는 게 아니고, 눈에 보이게 일하는 페이지가 조용히 생각만 하는 페이지보다 낫습니다. 소비자가 또 다른 기계라면, 예컨대 요금 비교 작업이나 확정된 답 하나가 필요한 기업 출장 예약 도구라면, 기다리는 쪽이 더 단순하고 옳을 때가 많습니다.
무엇을 고르든, 점진적 클라이언트를 건강하게 지키는 규칙은 세 가지입니다.
- 모든 묶음에는 검색 전체의 완료 상태가 실려 있어서, 클라이언트가 "아직 결과가 더 없음"과 "앞으로도 결과가 없음"을 구분할 수 있어야 합니다.
- 결과는 서버에서 안정적인 호텔 키로 병합되어야 하며, 뒤에 덧붙여지기만 해서는 안 됩니다. 두 카드가 같은 건물이라는 걸 클라이언트가 스스로 알아내야 하는 일은 없어야 합니다.
- 가격순 정렬은 검색이 끝날 때까지 잠정적이며, 인터페이스가 그 사실을 알려야 합니다. 사용자는 차츰 자리 잡는 목록은 용서하지만, 틀린 것으로 드러난 "최저가" 표시는 용서하지 않습니다.
무너지지 않는 객실·rate plan 모델링
대부분의 호텔 연동이 조용히 실패하는 지점이 여기이고, 그 실패는 몇 달 뒤 버그 리포트가 아니라 고객지원 티켓으로 나타납니다.
유혹적인 건 평평한 모델입니다. 호텔에 오퍼 목록이 있고, 오퍼마다 객실명과 가격이 있습니다. 화면에 잘 그려집니다. 그러다 어떤 공급사는 누가 봐도 같은 객실을 "Deluxe King"과 "Deluxe Room, 1 King Bed"로 보내고, 다른 공급사는 실제로 다른 두 객실(하나는 시티뷰, 하나는 아님)에 같은 이름을 붙이고, 세 번째 공급사는 다들 숙박 전체 가격을 줄 때 혼자 1박 가격을 줍니다. 평평한 목록은 지금 보고 있는 게 어느 경우인지 알려 주지 못합니다. 그냥 보여 줄 뿐입니다.
실제 공급사를 만나도 버티는 모델은 최소 네 단계로 나뉘고, 그 단계를 섞지 않습니다.
| 단계 | 담는 것 | 피해야 할 실수 |
|---|---|---|
| 호텔 | 자체적인 안정 ID, 각 공급사 코드와 매핑 | 공급사의 호텔 ID를 기본 키로 쓰기 |
| 객실 | 투숙 인원, 침대 구성, 공급사가 보낸 객실 원문 그대로 | 객실명을 "정리"하다가 서로 다른 두 객실을 하나로 합치기 |
| Rate plan | Board basis, 환불 가능 여부, 결제 방식, 출처 공급사 | 조식이나 환불 여부를 객실명의 일부로 취급하기 |
| 가격 | 숙박 전체 총액, 통화, 포함된 세금·수수료와 현지 결제분 | 1박 가격을 숙박 총액 옆에 나란히 표시하거나, 체크인 시 내는 수수료를 숨기기 |
경계를 어디에 긋는지는 의견이 갈릴 수 있습니다. 투숙 인원을 별도 단계로 떼어 내는 팀도 있는데, 다객실 예약을 팔기 시작하면 합리적인 선택입니다. 하지만 인터페이스가 그중 두 단계만 보여 준다는 이유로 단계를 합쳐서는 안 됩니다. 인터페이스는 렌더링할 때 평평하게 만들어도 됩니다. 데이터는 안 됩니다.
한 가지는 따로 한 문장을 쓸 만합니다. 정규화한 값이 무엇이든 그 옆에 공급사가 보낸 객실 설명 원문을 남겨 두십시오. 손님이 도착해서 바우처와 다른 객실을 받으면, 모두가 가장 먼저 묻는 건 공급사가 실제로 뭘 보냈느냐입니다.
취소 규정은 문단이 아니라 데이터
많은 공급사가 취소 조건을 자유 텍스트로 보냅니다. "도착 3일 전까지 무료 취소, 이후 1박 위약금." 그 문자열을 그대로 보여 주고 넘어가고 싶은 유혹이 큽니다.
그러지 마십시오. 텍스트는 비교도, 정렬도, 필터링도, 강제도 할 수 없습니다. 사용자는 환불 가능한 요금만 걸러 보고 싶어 합니다. 재무팀은 어떤 예약이 내일부터 환불 불가가 되는지 알아야 여행사가 기한 전에 고객에게 연락할 수 있습니다. 예약 이후 흐름은 고객이 취소 버튼을 누르는 순간 정확히 얼마가 청구되는지 알려 줘야 합니다. 이 중 어느 것도 문장 위에서는 돌아가지 않습니다.
각 규정을 위약금 구간의 정렬된 목록으로 모델링하십시오. 이 시점부터 저 시점까지 위약금은 이 금액(또는 숙박의 몇 퍼센트, 또는 몇 박)이라는 식입니다. 경계는 타임존이 붙은 타임스탬프여야 하고, 그 타임존은 서버도 사용자도 아닌 호텔의 것이어야 합니다. "도착 3일 전"은 누구의 자정을 기준으로 세느냐에 따라 다른 순간이기 때문입니다. 공급사 원문은 구조화된 버전 옆에 저장하고, 화면에는 구조화된 버전을 보여 주고, 둘이 어긋나면 숨기지 말고 조사할 거리로 다루십시오.
그리고 규정은 검색 때만이 아니라 예약 시점에 다시 확인하십시오. 두 호출 사이에 규정이 바뀌는 일은 누구 예상보다 잦습니다.
잘못했을 때 실제로 치르는 비용
느린 검색은 전환을 잃게 만듭니다. 나쁘지만 눈에 보이는 문제라 누군가는 불평합니다. 비싼 실패는 조용한 실패입니다.
환불 가능으로 표시했는데 공급사는 환불 불가로 보는 요금은 스크린샷을 가진 고객과의 분쟁이 되고, 위약금은 대개 여행사가 떠안습니다. 1박 가격을 숙박 총액처럼 보여 주면 회계팀 누군가가 알아챌 때까지 원가 이하로 객실을 팝니다. 다른 객실과 합쳐진 객실은 네 식구를 2인실로 보냅니다. 한 번도 표시되지 않은 현지 결제 수수료는 별 다섯 개 리뷰를 chargeback으로 바꿉니다. 모두 첫 스프린트에서 "나중에 정리하자"는 꼬리표와 함께 내린 모델링 결정입니다.
캐시: 보관해도 되는 것과 절대 안 되는 것
호텔 API를 연동하는 팀은 결국 검색을 더 빠르고 싸게 만들려고 결과를 캐시해도 되는지 묻습니다. 답은 일부는 된다는 것이고, 그 경계가 어떤 성능 수치보다 중요합니다.
정적 콘텐츠, 즉 호텔명, 주소, 좌표, 사진, 편의시설 목록, 객실 설명은 거의 바뀌지 않으니 자체 저장소에 적극적으로 캐시해야 할 대상입니다. 저장과 노출 방식에 대한 공급사 약관은 확인하십시오. 제한을 두는 라이선스도 있습니다. 검색할 때마다 실시간으로 가져오는 건 이득 없이 느리기만 합니다.
실시간 요금과 가용성은 이야기가 다릅니다. 캐시된 가격은 공급사가 얼마를 청구할지에 대한 추측일 뿐이고, 공급사는 여러분의 추측을 존중하지 않습니다. 페이지 표시용으로 검색 결과를 짧게 캐시하는 건 괜찮을 수 있습니다. 단, 모든 예약 경로가 결제 전에 공급사에 다시 가격을 확인하고, 인터페이스가 가격 변동을 오류가 아닌 정상 결과로 다룬다면요. 검색 대비 예약 비율을 제한하는 공급사도 있습니다. 실제 트래픽을 숨기는 공격적 캐시는 기댈 만한 빈틈이 아닙니다.
절대 캐시하면 안 되는 건 약속을 뜻하는 모든 것입니다. 홀드된 가격 토큰, 예약 번호, 취소 위약금 견적. 이것들은 한 사용자와 한 순간의 것입니다.
완료라고 말하기 전에
실제 예약을 받기 전에 자신의 연동에 돌려 볼 만한 짧은 점검 목록입니다.
- 검색이 완료 상태를 돌려주고, 클라이언트는 그 전후로 다르게 동작한다.
- 호텔은 자체 ID로 키가 잡혀 있고, 각 공급사 코드가 거기에 매핑돼 있다.
- 화면에 무엇이 보이든 데이터에서 객실, rate plan, 가격은 별개의 객체다.
- 모든 가격이 1박 기준인지 숙박 전체 기준인지, 도착 시 무엇을 내는지 밝힌다.
- 취소 규정은 호텔 타임존 기준의 시간 구간별 위약금으로 저장되고, 원문도 함께 보관된다.
- 예약 경로는 누구에게든 청구하기 전에 가격과 규정을 다시 확인한다.
- 약속을 뜻하는 것은 어떤 것도 캐시에서 내보내지 않는다.
이 모든 걸 공급사마다 직접 만들지, 이미 이런 문제를 겪어 본 플랫폼에서 시작할지 저울질하고 있다면 코드만큼 계약 쪽도 중요합니다. 호텔 홀세일 계약과 bedbank 요금을 다룬 글에 무엇을 요구해야 하는지 정리해 두었습니다. 저희 항공·호텔 API는 셀프서비스 키가 아니라 대화를 통해 열립니다. 그 길을 검토하고 싶다면 travel APIs 페이지에서 대화를 시작하십시오.
fan-out은 사라지지 않습니다. 좋은 클라이언트는 그저 그것이 없는 척하기를 멈출 뿐입니다.