Restful API 錯誤訊息設計，200, 400 要選哪個？

Kostiantyn Li on Unsplash

Let's think about design of error message of Restful API

前陣子，合作的同事捎來訊息來討論某產品在被呼叫了功能不支援的 API 後的訊息回應方式，原本的設計方式是 API 被呼叫後會回傳一個訊息代碼 200 跟一組帶有數個空白欄位跟一個 false 欄位的資料封包。

同事說：「當這產品的這個 API 被呼叫，再從回傳內容的某個欄位欄位來判斷，只要“這個欄位”顯示 false 就代表不支援」，雖然這樣的設計也能滿足功能需求，不過還是想聽聽我的意見。

/* Example of API response. */
{
	code:200,
	data:{
		A:"",
		B:"",
		F:false,
	}
}

什麼是 API？

可能有不少人沒聽過 API，在軟體設計裡提到的 API 是指 Application Interface 也叫做應用程式介面，透過 API 來整合功能是現代的軟體開發主要實現手段之一。

這是一種利用積木堆疊概念來實作軟體功能的方式，軟體工程師按照業務流程來呼叫程式語言內的功能模塊，每個功能模塊都會提供一個或多個介面讓呼叫端透過不同參數輸入來取得功能模組的執行結果，藉此設計組合來達到軟體功能設計目的。一個有經驗的軟體團隊會隨時間逐漸累積組織業務所需的 API 或開發應用框架來進一步降低開發成本。對現在的軟體工程師而言，要熟稔 API 技術與文件早已是基本功了。

API 的類型有很多種，這裡我們聊的是 Restful API，它是基於 HTTP 通訊協定的技術，協議要求每個 Restful API 被呼叫後一定都要有回應（除非網站掛掉），內容包一個數字訊息代碼（Message Code）跟零個或一個的資料封包（Response）。

不同的類型訊息代碼有不同的意義，例如常見的有 200, 400, 500 系列，只要呼叫端看到對方 API 回應是 200 系列的數值，就知道這次呼叫成功且對方 API 正確執行，出現 400 代表有呼叫成功但是對方 API 沒有正常執行或出現錯誤，出現 500 也是錯誤的一種，代表伺服器出現異常還沒把收到的參數資料傳給後台 API 就掛掉，是終止服務的狀態。

設計沒有對錯

再回到我們的問題，那麼當產品被呼叫了功能不支援的 Restful API 後，它應該回覆訊息代碼 200 跟有著某個 flag 代表不支援的回應封包或是回覆訊息代碼 400 跟帶有一串錯誤訊息的回應封包呢？答案見仁見智，就像小朋友們面對青椒的反應類似，一班小朋友都不太喜歡吃青椒，很直接就顯露出嫌惡表情（訊息代碼 400）跟語氣：「我．不．要．吃．青．椒！」（錯誤訊息）

當小孩們變成大人後會不太好意思直接拒絕他人，學會間接的方式來表達自己的「感覺」，想知道一道菜好不好吃、喜不喜歡吃需要旁敲側擊，是要觀察夾菜頻率呢？還是要確認剩菜份量？結果就是「都可以，也都不可以」，要猜測一個不確定的結果需要讀心術，這可不是人人都練得動的技能。

真相不止一個

在軟體設計裡面，相同功能會因為設計者的理念呈現出不同的樣貌。

偏好第一種設計就比較像大人的內斂表，接收端很難解讀出真正的意思，到底是產品功能不支援還是 API 運作的結果正常但回傳數值是空白呢？還是因為剛好這次運氣不好出現不正常結果，是不是要多試幾次下次是不是就正常有數值了呢？來回確認很多次需要更多的判斷條件會讓程式變得非常複雜，又臭又長。

喜歡第二種設計方式的人，選擇直球對決。就像小朋友討厭青椒的反應訊息明確，接收端只需要寫一個判斷條件就能處理沒有懸念，程式碼便得簡潔有力。

沒意外地我投了 400 一票。