Restful API 設計的 8 個訣竅

在設計 RESTful API 時,有幾個關鍵要點需要特別注意,因爲這些要點如果處理不好,容易導致錯誤或降低 API 的可用性和維護性。

01 領域模型

在設計 RESTful API 的路徑結構時,可以參考領域模型。在領域驅動設計思想中,領域模型構成了軟件的邏輯結構。

這樣設計有幾個好處:

02 選擇合適的 HTTP Methods

HTTP 協議提供了非常多種 Methods,但對於應用系統而言,使用過多的 HTTP Methods 會給開發者帶來困擾。

因此,定義基本的幾個 HTTP Methods 可以簡化 API 設計,這取決於團隊風格。

例如,PATCH 在很多時候會給團隊造成困擾,開發者往往不能清晰地辨別在何種場景下使用 PATCH 還是 PUT,因此根據團隊約定,可以統一使用 PUT。

03 冪等

提前進行冪等性設計可以提高 API 的健壯性。

04 選擇合適的 HTTP 狀態碼

和 HTTP Methods 類似,HTTP 狀態碼也非常多。根據經驗,開發者在選擇使用哪一個狀態碼時,非常容易犯錯,且難以在團隊內達成統一。

比較好的方法是,定義有限的 HTTP 狀態碼來使用即可,來簡化應用開發的難度。例如,當發生校驗錯誤時,統一返回 400,當發生業務錯誤時,統一返回 419。

05 版本控制

提前爲 API 設計版本號可以簡化後期的改造和升級工作。

API 版本信息通常有三種方式:

比較推薦的方法是使用 Path 前綴,對於提供者和消費者來說都非常容易理解,且不會侵入其它的業務參數。

06 語義化 API 路徑

讓 API Path 保持語義化可以增加 API 的辨識度,讓消費者更容易在文檔中找到合適的 API。

提高語義化的方法有:

07 批量處理

提前爲批量 API 設定一套規則,讓批量 API 更加語義化。我們可以進行約定:

08 查詢語言設計

提前設計一套具有拓展性的查詢規則,可以讓 API 更加靈活。

GET /v1/users?age=gt:20,lt:50&name=match:lisa&gender=eq:male

其中,gt 代表大於,lt 代表小於,match 代表模糊搜索,eq 代表完全匹配。

本文由 Readfog 進行 AMP 轉碼,版權歸原作者所有。
來源https://mp.weixin.qq.com/s/maHZxoYlt960n7RzonLdmQ