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

閱讀時間約 3 分鐘

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 一票。

14會員
61內容數
WarrenLo's 軟體設計武功祕笈
留言0
查看全部
發表第一個留言支持創作者!
Warren Lo的沙龍 的其他內容
關於程式語言的學習,只要掌握住幾個基本特性要熟悉幾種程式語言也不困難,這三個基本特性就是…
IDE 升級後出現了一樣的錯誤,手上程式碼沒有 pylint black-format 檢查上不了 gitlab,我又點開了那個很小很小的 x 符號,裡面 logs 提示的解決方式是升級..
在網路上查找可以發現有很多類別圖的 6 種關係的說明與示例,通常不太容易難取得共鳴。主要有兩個原因: 1. 對於這些關係線的定義混淆,導致無法判斷滿足條件與使用時機 2. 缺少生活相關的具體案例,很難理解這些關係所對應的抽象概念
UART 轉換完成的 Serial 訊號已經可以用來傳輸通訊了,那為什麼還要把 UART 轉出來的訊號再轉換成成其他的 Serial 介面,像是 RS232/RS485 再進行傳輸呢?原因是 UART 的 Serial 訊號傳輸的距離實在太短了
Serial 通訊數據必須先在 UART 元件把 Parallel 轉成 Serial,EIA Driver 會把 Serial 轉成特定的 Serial 訊號。UART 數據轉換要考慮兩個關鍵點,如何讓資料從直行變橫列(躺平)的方法,還要考慮如何控制 Serial 訊號輸出
聊到 Serial 通訊就一定會提到 COM Port,它是微軟定義的一個經典 Serial 通訊實作。COM Port 在筆電還不普及的年代可以很輕鬆在 PC(桌機)的主機板上找到有標示 COM1 或者 COM2 的通訊接口,這些就是最常見的 COM Port 通常搭載的都是 R232 的通訊規格
關於程式語言的學習,只要掌握住幾個基本特性要熟悉幾種程式語言也不困難,這三個基本特性就是…
IDE 升級後出現了一樣的錯誤,手上程式碼沒有 pylint black-format 檢查上不了 gitlab,我又點開了那個很小很小的 x 符號,裡面 logs 提示的解決方式是升級..
在網路上查找可以發現有很多類別圖的 6 種關係的說明與示例,通常不太容易難取得共鳴。主要有兩個原因: 1. 對於這些關係線的定義混淆,導致無法判斷滿足條件與使用時機 2. 缺少生活相關的具體案例,很難理解這些關係所對應的抽象概念
UART 轉換完成的 Serial 訊號已經可以用來傳輸通訊了,那為什麼還要把 UART 轉出來的訊號再轉換成成其他的 Serial 介面,像是 RS232/RS485 再進行傳輸呢?原因是 UART 的 Serial 訊號傳輸的距離實在太短了
Serial 通訊數據必須先在 UART 元件把 Parallel 轉成 Serial,EIA Driver 會把 Serial 轉成特定的 Serial 訊號。UART 數據轉換要考慮兩個關鍵點,如何讓資料從直行變橫列(躺平)的方法,還要考慮如何控制 Serial 訊號輸出
聊到 Serial 通訊就一定會提到 COM Port,它是微軟定義的一個經典 Serial 通訊實作。COM Port 在筆電還不普及的年代可以很輕鬆在 PC(桌機)的主機板上找到有標示 COM1 或者 COM2 的通訊接口,這些就是最常見的 COM Port 通常搭載的都是 R232 的通訊規格
你可能也想看
Google News 追蹤
Thumbnail
這個秋,Chill 嗨嗨!穿搭美美去賞楓,裝備款款去露營⋯⋯你的秋天怎麼過?秋日 To Do List 等你分享! 秋季全站徵文,我們準備了五個創作主題,參賽還有機會獲得「火烤兩用鍋」,一起來看看如何參加吧~
Thumbnail
美國總統大選只剩下三天, 我們觀察一整週民調與金融市場的變化(包含賭局), 到本週五下午3:00前為止, 誰是美國總統幾乎大概可以猜到60-70%的機率, 本篇文章就是以大選結局為主軸來討論近期甚至到未來四年美股可能的改變
Thumbnail
Faker昨天真的太扯了,中國主播王多多點評的話更是精妙,分享給各位 王多多的點評 「Faker是我們的處境,他是LPL永遠繞不開的一個人和話題,所以我們特別渴望在決賽跟他相遇,去直面我們的處境。 我們曾經稱他為最高的山,最長的河,以為山海就是盡頭,可是Faker用他28歲的年齡...
Thumbnail
RESTful Web 服務是現代 Web 和移動應用的核心,它們提供了一個標準化的方式來互動和交換數據。使用Gin構建這些服務是一種流行選擇,還記得之前提過的 嗎?本文將介紹一些最佳實踐,幫助你創建高效和可維護的RESTful服務。
Thumbnail
大家好!隨著微服務和前後端分離的架構日益普及,RESTful API 已經成為 Web 開發的核心。透過 Gin,我們可以輕鬆地設計和實現高效能的 API。今天,我們就來探討如何在 Gin 中設計優雅且實用的RESTful API
Thumbnail
上一篇我們有介紹什麼是OPA以及一些基本概念「【資訊軟體知識】Open Policy Agent 授權策略」,接下來我們就來介紹如何架設並以API的方式進行授權檢查。 這種方式的好處是可以跨語言, 不侷限於Go, 透過標準RESTFUL API的方式來與OPA Server相互溝通。 使用Docke
Thumbnail
這裡會針 GraphQL 與 RESTful API 這兩者介面所需要做的事情來比較其應用的場景。
Thumbnail
Restful API 其實就是開放一個 EndPoit 的網路接口給其他人使用,並將要做的事情封裝在該接口內,不需要知道真實運作狀況,只要得到答案即可。
Thumbnail
API Gateway 是什麼? 參考上圖,API Gateway 是一個程式,位於 Client 和 Microservice 之間。當伺服器架構採用這種設計後,會有以下優點: 架構彈性 - 當伺服器架構需要調整的時候,Client 不需要調整(前提是 API 維持不變)。 IP Listing
Thumbnail
網址是 API 的門面,大家使用 API 的第一步就是要看它。 第一眼就要讓人就知道這隻 API 在做什麼? 甚至因為遵循標準(目前 REST 是主流),可以類推 API 應該會有什麼功能等等。
Thumbnail
本筆記遵循官方文件教學,經過一些小修改,經測試可以跑在Laravel Framework version: 8.13.0,將筆記記錄下來。 ......
REST全名為Representational State Transfer,它是一種軟體架構風格,不是一種標準。 以REST架構設計的系統就可以稱為 RESTful,就像是美麗 (Beauty) 的事物可以稱為 Beautiful。
Thumbnail
這個秋,Chill 嗨嗨!穿搭美美去賞楓,裝備款款去露營⋯⋯你的秋天怎麼過?秋日 To Do List 等你分享! 秋季全站徵文,我們準備了五個創作主題,參賽還有機會獲得「火烤兩用鍋」,一起來看看如何參加吧~
Thumbnail
美國總統大選只剩下三天, 我們觀察一整週民調與金融市場的變化(包含賭局), 到本週五下午3:00前為止, 誰是美國總統幾乎大概可以猜到60-70%的機率, 本篇文章就是以大選結局為主軸來討論近期甚至到未來四年美股可能的改變
Thumbnail
Faker昨天真的太扯了,中國主播王多多點評的話更是精妙,分享給各位 王多多的點評 「Faker是我們的處境,他是LPL永遠繞不開的一個人和話題,所以我們特別渴望在決賽跟他相遇,去直面我們的處境。 我們曾經稱他為最高的山,最長的河,以為山海就是盡頭,可是Faker用他28歲的年齡...
Thumbnail
RESTful Web 服務是現代 Web 和移動應用的核心,它們提供了一個標準化的方式來互動和交換數據。使用Gin構建這些服務是一種流行選擇,還記得之前提過的 嗎?本文將介紹一些最佳實踐,幫助你創建高效和可維護的RESTful服務。
Thumbnail
大家好!隨著微服務和前後端分離的架構日益普及,RESTful API 已經成為 Web 開發的核心。透過 Gin,我們可以輕鬆地設計和實現高效能的 API。今天,我們就來探討如何在 Gin 中設計優雅且實用的RESTful API
Thumbnail
上一篇我們有介紹什麼是OPA以及一些基本概念「【資訊軟體知識】Open Policy Agent 授權策略」,接下來我們就來介紹如何架設並以API的方式進行授權檢查。 這種方式的好處是可以跨語言, 不侷限於Go, 透過標準RESTFUL API的方式來與OPA Server相互溝通。 使用Docke
Thumbnail
這裡會針 GraphQL 與 RESTful API 這兩者介面所需要做的事情來比較其應用的場景。
Thumbnail
Restful API 其實就是開放一個 EndPoit 的網路接口給其他人使用,並將要做的事情封裝在該接口內,不需要知道真實運作狀況,只要得到答案即可。
Thumbnail
API Gateway 是什麼? 參考上圖,API Gateway 是一個程式,位於 Client 和 Microservice 之間。當伺服器架構採用這種設計後,會有以下優點: 架構彈性 - 當伺服器架構需要調整的時候,Client 不需要調整(前提是 API 維持不變)。 IP Listing
Thumbnail
網址是 API 的門面,大家使用 API 的第一步就是要看它。 第一眼就要讓人就知道這隻 API 在做什麼? 甚至因為遵循標準(目前 REST 是主流),可以類推 API 應該會有什麼功能等等。
Thumbnail
本筆記遵循官方文件教學,經過一些小修改,經測試可以跑在Laravel Framework version: 8.13.0,將筆記記錄下來。 ......
REST全名為Representational State Transfer,它是一種軟體架構風格,不是一種標準。 以REST架構設計的系統就可以稱為 RESTful,就像是美麗 (Beauty) 的事物可以稱為 Beautiful。