API 문서를 UX 관점에서 만든다고 하면 ‘API 문서는 일반 고객에게 보이지 않을 텐데?’라고 생각하는 분들이 많을 겁니다. 보통 UX는 소프트웨어와 같은 서비스의 사용자 경험을 말하니까요. B2B 솔루션 기업 ONDA가 이 방법을 택한 이유는 무엇일까요?
먼저 ONDA의 서비스를 되짚어 볼 필요가 있습니다. 펜션부터 호텔까지, 숙소가 편리하게 운영할 수 있도록 하는 다양한 솔루션 가운데 대표적으로는 통합 판매 시스템 ONDA HUB가 있는데요.
객실 재고와 가격을 여러 판매 사이트와 연동하여 숙소는 에어비앤비, 아고다 같은 여러 OTA에 ‘한 번에' 판매할 수 있습니다. 즉, 숙소와 판매사이트 사이에서 이들을 연결하는 중간 다리 역할을 하는 건데요. 왜 이런 기술 혁신이 필요할까요?
숙소와 판매 사이트 사이의 일은 여전히 오프라인에서 이뤄지는 경우도 빈번할뿐더러, 숙소가 판매 사이트별로 일일이 입점한다면 A 사이트에서 예약이 들어왔을 때 B 사이트 재고를 수동으로 조절해야 하는 번거로움이 있기 때문이죠. 이때 시기를 놓치면 중복 예약이 발생할 수도 있고요.
ONDA HUB는 이런 불편함을 없애고 기술로 시간과 인력을 효율적으로 활용할 수 있게 합니다.
통합 판매 시스템은 크게 판매 사이트 연동과 숙박 상품 공급 연동으로 나뉘며, 현재 4만 개 이상의 숙박 상품(숙소)을 가지고 있고 40개 이상의 판매 사이트와 연동되어 있습니다.
제가 속한 PO(Product Owner, 보통 소프트웨어 서비스에서 제품을 기획하고 만들어 나가는 역할을 말합니다) 팀은 통합 판매 시스템의 기반이 되는 네트워크 확장을 목표하고 있어요. 더 많은 숙소를 공급하기 위해 외부 공급사와 연동하고, 공급받은 숙소를 더 잘 팔기 위해 (이미 국내외 주요 OTA와 연동되어 있지만) 다양한 판매 사이트와 연동하는 것에 힘쓰고 있죠.
이 과정에서 가장 중심이 되는 것 중 하나가 API* 문서입니다. 시스템을 연동하는 작업은 API 문서를 이해하는 데서 시작할 수 있기 때문이에요.
즉 API는 회사 대 회사(혹은 부서 대 부서)가 데이터를 주고받을 수 있는 하나의 출입문을 말해요.
ONDA API의 핵심은 숙소 정보를 가져와 판매 사이트로 보내고, 사이트에서 생성된 예약을 다시 숙소로 전달하는 일이기에, 숙박 상품 공급사 혹은 판매사와 어떤 방식으로 데이터를 전달할지 약속한 내용을 API 문서에서 확인할 수 있죠.
그런데, 다른 사람이 작성한 API 문서를 이해하는 건 쉬운 일이 아닙니다. 어떤 API가 있고, 어떻게 동작하며, 어떤 결과를 반환하는지 등의 스펙(명세)이 회사마다 다르거든요. 더욱이 영어나 숫자로 이루어진 문서라 API 문서를 처음 보는 사람은 이해하기 어려울 겁니다.
그러다 보면 API 문서에 관해 설명하고 맥락을 전달하는 일에 가장 많은 시간을 할애하게 됩니다. 서로 이 문서를 이해하기 위해 질문하고 답변하는 일이 여러 차례 반복되는 거죠.
따라서 커뮤니케이션 코스트를 줄이고 효율적으로 연동하기 위해서는 문서의 양식이 무척 중요합니다. 명쾌한 언어로 문서를 작성하고, 파트너가 직접 테스트할 수 있다면 협력하는 파트너(ONDA에게는 판매사와 공급사가 되겠죠)의 리소스를 아낄 뿐만 아니라 커뮤니케이션 오류로 발생할 수 있는 문제를 사전에 방지할 수 있습니다.
많은 서비스를 써보며 시행착오를 겪었는데요. 결과적으로 ‘Readme’라는 툴을 사용하고 있습니다. 아마 API를 설계하거나 개발하는 분들이라면 잘 아실 텐데요. 단순히 API 스펙(명세)을 보기 좋게 문서화하는 것뿐만 아니라, 파트너들이 직접 테스트를 할 수 있어 문서의 이해도를 높일 수 있다는 것이 가장 큰 장점으로 다가왔습니다.
예를 들어 외국인에게 김치찌개의 맛을 설명할 때 “김치에서 우러난 국물로 매콤하고 감칠맛이 나"라고 말로만 설명하면 이해하기 어려운데, 한 번 먹어보게 하면 바로 맛을 알 수 있잖아요. 마찬가지로 복잡한 API 문서를 처음부터 다 읽는 것보다 문서 내에서 실제로 호출(Request)하고 응답(Response)할 수 있게 하는 거죠.
.gif)
물론 Readme를 사용하는 초기에는 어려움을 겪었습니다. 같은 산업이더라도 업체나 시스템마다 사용하는 용어가 조금씩 다르기 때문에 응답(Response)의 각 항목(Response Body)에 관해 설명과 타입을 명시할 필요가 있는데, Readme에서 제공하는 기본 에디터로는 한계가 있었거든요.
국내 1위 암호화폐 거래소인 ‘업비트’도 동일한 문제를 겪었던 건지 문서의 본문에 응답(Response)을 줄글로 명세하는 방식을 선택했더라고요. 하지만 이는 좋은 사례라고 생각되는 ‘에어비앤비’의 방식에 비하면 아쉬움이 남았습니다.
두 문서의 차이는 Readme에서 제공하는 기본 에디터를 사용하느냐, 아니면 OAS(OpenAPI Specification)라는 일종의 표준 스펙을 사용하느냐입니다.
OAS는 간단히 말하자면 RESTful API(두 컴퓨터 시스템이 인터넷을 통해 정보를 안전하게 교환하기 위해 사용하는 인터페이스)를 명시하기 위한 표준인데요. 해당 표준의 가장 큰 장점은 언어에 구애받지 않는 json과 yaml 형태를 이용하기 때문에 모든 서비스에서 누구나 이용할 수 있다는 것입니다. (좀 더 상세한 설명이 궁금하신 분을 위해 링크를 남깁니다)
저희에겐 판매사나 공급사와 API를 연동할 때 만나는 개발자, 혹은 PM(Product Manager)이 고객이니, 좋은 UX 관점에서 프로덕트를 제공하고자 응답(Response)의 각 항목을 직관적으로 볼 수 있도록 OAS 형식에 맞춰서 업로드하는 방법을 택하게 됐죠.
회사마다 API 문서를 남기는 방식이나 주체가 조금씩 다르겠지만 ONDA는 PO가 중심이 되어 이를 관리하고 있습니다. 공급사나 판매사와 소통하는 주체이기도 하고, 내부 개발자들과 협업할 때도 구체적인 명시가 필요하기 때문이죠.
개발자가 아닌 PO, PM이 OAS 형식에 따라 좋은 API 문서를 만들기 위해 어떤 것을 도입했을까요?
OAS는 개발 언어에 구애받지 않는 yaml과 json 형태를 이용합니다. yaml과 json은 데이터 전송 시 포맷 규칙을 말하는데요. json은 []나 {} 같은 문자들이 있어 조금은 복잡한 느낌이 듭니다. 팀원들은 어느 정도 개발에 대한 이해가 있어 무엇을 선택해도 상관없었지만, 개발 언어에 익숙하지 않은 분을 위해 인간 친화적인 형태의 yaml을 선택했습니다.
Swagger Editor처럼 쉬운 OAS 작성을 지원하는 좋은 툴은 이미 존재했는데요. 협업이나 좀 더 쉬운 사용을 위해서는 OAS 작성 외에도 더 좋은 기능을 제공하는 툴이 필요했고, vscode가 적합했습니다. 몇 가지 Extension(확장 프로그램)을 통해 OAS 문법을 잘 모르는 사람도 문제를 최소한으로 겪을 수 있거든요.
지속적인 관리를 위해서는 협업이 가장 중요하기에 github에 OAS 작성 코드를 올리고 있습니다. 개발에 익숙한 분들은 vscode에서 CLI(Command line interface, 명령 줄 인터페이스라 불리며 사용자가 텍스트로 작업 명령을 입력하면 컴퓨터 역시 문자열로 출력하는 것)를 이용할 텐데요. 이 역시 GUI(graphical user interface, 그래픽 사용자 인터페이스라 불리며 입출력 등의 기능을 알기 쉬운 아이콘 따위의 그래픽으로 나타낸 것)로 할 수 있는 앱을 다운로드하여 보다 직관적으로 작성하고 공유합니다.
단순히 스펙을 명시하는 게 아닌, 하나의 프로덕트 관점에서 기존의 API 문서를 개선한 이후 연동 시작 시 이를 상세히 설명하지 않게 되었습니다. 질문이 들어오더라도 문서에 바로 반영하여 반복적인 질문이 오고 가는 게 현저히 줄었는데요. 이전과 비교하면 거의 90% 이상 질문이 줄었죠.
물론 여러 문서를 관리하지 않으면서 명쾌하게 설명할 수 있어 내부 만족도도 높고요.
안타깝게도 이전의 운영 시스템을 사용하는 파트너와 협력하다 보면 API 문서를 PDF 형식으로 주는 곳도 있습니다. 단순히 툴과 양식을 떠나, 파트너를 고객으로 대하고 UX 관점에서 어떤 문서를 전하는가는 앞으로도 굉장히 중요합니다. 파트너와 빠르게 연동할수록 우리의 네트워크가 커지는 속도가 빨라질 테니 말이죠.
