TL;DR

B2B 解決方案公司 ONDA 為什麼在意「好的」API 文件

說要從 UX 的角度製作 API 文件，大概很多人會想:「API 文件一般客戶又看不到?」畢竟 UX 通常指的是軟體等服務的使用者體驗。B2B 解決方案公司 ONDA 為什麼選擇這麼做?

ONDA 在機會之地創造革新

先回頭看看 ONDA 的服務。從民宿到飯店，讓旅宿業者能便利營運的各種解決方案當中，最具代表性的就是整合銷售系統 ONDA HUB。

客房庫存與價格與多個銷售通路連動，旅宿業者能「一次」在 Airbnb、Agoda 等多個 OTA 上銷售。也就是在旅宿與銷售通路之間扮演中間橋樑的角色。為什麼需要這樣的技術革新?

旅宿與銷售通路之間的作業還是經常在線下進行，而且如果旅宿要逐一在各個銷售通路上架，當 A 通路有訂單進來時，就得手動調整 B 通路的庫存，非常麻煩。錯過時機的話還可能發生重複訂房的問題。

ONDA HUB 消除這些不便，用技術讓時間與人力得到有效運用。

整合銷售系統連動的基礎: API 文件

整合銷售系統大致分為銷售通路連動與住宿商品供應連動，目前擁有超過 4 萬個住宿商品(旅宿)，並與 40 個以上的銷售通路連動。

我所屬的 PO(Product Owner，通常指軟體服務中負責規劃與打造產品的角色)團隊，目標是擴大作為整合銷售系統基礎的網路規模。為了提供更多旅宿，我們與外部供應商連動;為了更好地銷售取得的旅宿(雖然已經與國內外主要 OTA 連動)，我們致力於和各種銷售通路連動。

**這個過程中最核心的要素之一就是 API* 文件。**因為連動系統的工作，得從理解 API 文件開始。

*這裡先說明，什麼是 API?

Application Programming Interface(應用程式介面)的縮寫，是讓兩個軟體元件能彼此溝通的機制。它定義了使用請求與回應進行溝通的方法，API 文件包含如何構成這些請求與回應的資訊。(出處: AWS)

簡單說，API 就是公司對公司(或部門對部門)能交換資料的出入口。

ONDA API 的核心是取得旅宿資訊傳送到銷售通路，再把通路產生的訂單傳回旅宿，所以在 API 文件中能確認與住宿商品供應商或銷售商約定以什麼方式傳遞資料。

**然而，理解別人寫的 API 文件並不容易。**因為每家公司有哪些 API、如何運作、回傳什麼結果等規格(spec)都不同。更何況文件充滿英文與數字，第一次看 API 文件的人會覺得很難懂。

於是最花時間的事情，就變成解釋 API 文件、傳達脈絡。彼此為了理解這份文件，問答來回好幾次。

降低溝通成本的選擇: Readme 與 OAS

因此，要降低溝通成本、有效率地連動，文件的格式非常重要。用清晰的語言撰寫文件，讓合作夥伴能直接測試，不只節省合作夥伴(對 ONDA 來說就是銷售商與供應商)的資源，也能事先防止因溝通錯誤而產生的問題。

Airbnb、Upbit、當地直送等許多公司都在用 Readme。
Airbnb、Upbit、當地直送等許多公司都在用 Readme。

試用許多服務、歷經試錯之後，我們最終選擇了「Readme」這個工具。設計或開發 API 的人應該都知道。它不只是把 API 規格(spec)整理成好看的文件，更大的優點是合作夥伴能直接測試，提升對文件的理解度。

舉例來說，要向外國人說明泡菜鍋的味道，光用「用泡菜熬出的湯頭，又辣又鮮」這樣口頭描述會很難理解，但讓對方嚐一口，馬上就懂了。同樣的道理，與其從頭到尾讀完複雜的 API 文件，不如讓使用者在文件內直接呼叫(Request)並取得回應(Response)。

能在 API 文件內直接測試。
能在 API 文件內直接測試。

當然剛開始使用 Readme 時也遇到困難。即使是同一個產業，不同業者或系統使用的術語也會有些微差異，因此需要對回應(Response)的每個項目(Response Body)標示說明與類型，但 Readme 提供的基本編輯器有其限制。

韓國最大的加密貨幣交易所「Upbit」似乎也遇到同樣的問題，選擇在文件本文中用敘述方式說明回應(Response)。但這跟被認為是良好範例的「Airbnb」做法相比，還是有些可惜。

Upbit API 文件
Upbit API 文件

  • 雖然用表格整理得很清楚、理解上沒什麼困難，但實際回應(Response)部分沒有標示，要掌握結構有其限制。

Airbnb API 文件
Airbnb API 文件

  • 標示各項目是什麼、格式為何、可能包含哪些項目的範例等，不用翻來翻去就能輕鬆理解。

兩份文件的差異在於，是使用 Readme 提供的基本編輯器，還是使用一種名為 OAS(OpenAPI Specification)的標準規格。

簡單來說，OAS 是用於描述 RESTful API(兩個電腦系統透過網路安全交換資訊時使用的介面)的標準。這套標準最大的優點是使用不受語言限制的 json 與 yaml 格式，所有服務的任何人都能使用。(想了解更詳細說明的讀者可參考連結)

對我們來說，與銷售商或供應商連動 API 時接觸的開發者或 PM(Product Manager)就是客戶，為了從良好的 UX 角度提供產品，我們選擇按照 OAS 格式上傳，讓回應(Response)的各項目能直觀呈現。

為了做出好的 API 文件而導入的工具

各家公司留存 API 文件的方式或負責主體可能略有不同，但 ONDA 是以 PO 為中心進行管理。因為 PO 是與供應商或銷售商溝通的主體，與內部開發者協作時也需要具體說明。

非開發者的 PO、PM 要按照 OAS 格式製作好的 API 文件，導入了什麼工具呢?

✔️ yaml

OAS 使用不受開發語言限制的 yaml 與 json 格式。yaml 與 json 是指資料傳輸時的格式規則，json 有 [] 或 {} 這類符號，感覺有點複雜。團隊成員對開發都有一定程度的理解，選哪個都可以，但為了不熟開發語言的人，我們選擇了人類友善的 yaml 格式。

撰寫 API 文件時採用「yaml」格式。
撰寫 API 文件時採用「yaml」格式。

✔️ vscode

像 Swagger Editor 這種支援簡易 OAS 撰寫的好工具已經存在了，但為了協作或更方便使用，除了 OAS 撰寫之外還需要提供更多功能的工具，vscode 很合適。透過幾個 Extension(擴充功能)，即使不熟 OAS 語法的人也能把問題降到最低。

vscode 有很多很棒的擴充功能。
vscode 有很多很棒的擴充功能。

✔️ github desktop

為了持續管理，協作最重要，所以我們把 OAS 撰寫的程式碼上傳到 github。熟悉開發的人會在 vscode 中使用 CLI(Command line interface，命令列介面，使用者以文字輸入作業指令，電腦也以字串輸出)。這部分也能用 GUI(graphical user interface，圖形化使用者介面，將輸入輸出等功能用易懂的圖示等圖形呈現)應用程式，下載後能更直觀地撰寫與分享。

問題數量減少超過 90%

ONDA 的 API 文件，改善後溝通成本顯著降低。
ONDA 的 API 文件，改善後溝通成本顯著降低。

不只是標示規格，而是從產品的角度改善既有 API 文件之後，連動開始時就不用詳細說明了。即使有問題進來，也會立刻反映在文件中，重複的提問明顯減少。與之前相比，問題減少了 90% 以上。

當然，不用管理多份文件就能清楚說明，內部滿意度也很高。

可惜的是，與使用舊營運系統的合作夥伴協作時，還是有地方會提供 PDF 格式的 API 文件。拋開工具與格式不談，把合作夥伴當成客戶、從 UX 角度提供什麼樣的文件，今後依然非常重要。因為與合作夥伴連動得越快，我們的網路擴展速度就越快。