在項目開發(fā)中，我們經(jīng)常會使用REST風(fēng)格進(jìn)行API的定義，這篇文章為大家提供10條在使用REST API時的最佳實踐。希望能夠為你帶來靈感和幫助。
1、使用具體且有意義的資源名稱
選擇能準(zhǔn)確表示所代表實體的資源名稱，而不要使用泛化或模糊的名稱。
圖片
這一條最佳實踐非常明確，也就是說我們在使用REST API時，代表資源分類的部分，比如上圖中的“users”和“customers”，使用users更泛化，不夠具體，可能是To C的用戶，也可能是To B或To G的用戶。此時，最近確保定義的資源更具體，能夠代表一定的清晰含義。
2、正確使用HTTP方法
根據(jù)不同的操作使用合適的HTTP方法（GET、POST、PUT、DELETE、PATCH等）。
圖片
這一條涉及到HTTP方法的基本定義。舉一個簡單的例子來說明就是：一般提交表單操作，用POST請求，查詢信息用GET請求。不要將兩者顛掉或混用。當(dāng)然，還有其他的HTTP方法，也是如此。
3、對API進(jìn)行版本控制
使用版本控制確保向后兼容性，并允許在不破壞現(xiàn)有客戶端的情況下進(jìn)行未來的增強。
圖片
為了保持版本的兼容性，依舊流量和功能的控制等，通常需要對API進(jìn)行版本控制，這個是僅限于REST API，而是比較通用的一條最佳實踐，特別是真的終端是App的情況。
4、正確使用HTTP狀態(tài)碼
返回適當(dāng)?shù)腍TTP狀態(tài)碼以指示API請求的成功或失敗。
圖片
這一條也是非常基礎(chǔ)的HTTP知識，不同的錯誤碼代表著不同的含義，準(zhǔn)確的返回錯誤碼，可以讓終端更加精準(zhǔn)的識別錯誤。
5、選擇JSON字段命名約定
JSON標(biāo)準(zhǔn)沒有強制規(guī)定字段命名約定，但最佳實踐是選擇一個并堅持使用。
圖片
選擇適合團(tuán)隊和編程語言的JSON命名規(guī)則，具體采用哪種不重要，重要的是整個團(tuán)隊要確保統(tǒng)一。在個人的團(tuán)隊中，更習(xí)慣使用駝峰（camelCase）的形式。
6、使用一致的錯誤信息
在大多數(shù)情況下，僅使用HTTP狀態(tài)碼無法解釋出現(xiàn)的錯誤。為了幫助API使用者，包含一個結(jié)構(gòu)化的JSON錯誤消息。這里的JSON錯誤信息更偏向業(yè)務(wù)層面。而HTTP狀態(tài)碼更偏向于HTTP交互層面。
響應(yīng)應(yīng)包括以下信息：
- 錯誤代碼：機器可讀的錯誤代碼，用于識別特定的錯誤條件。
- 錯誤消息：人類可讀的消息，提供對錯誤的詳細(xì)解釋。
- 錯誤上下文：與錯誤相關(guān)的附加信息，例如請求ID、導(dǎo)致錯誤的請求參數(shù)或?qū)е洛e誤的請求中的字段。
- 錯誤鏈接：提供有關(guān)錯誤以及如何解決錯誤的附加信息或文檔的URL。
- 時間戳：錯誤發(fā)生的時間。
7、使用查詢參數(shù)進(jìn)行過濾、排序和搜索
查詢參數(shù)允許你在HTTP請求的URL中提供額外的信息，以控制服務(wù)器返回的響應(yīng)。
圖片
8、實施身份驗證和授權(quán)
通過實施適當(dāng)?shù)纳矸蒡炞C和授權(quán)機制來保護(hù)API。
建議：
- 使用API密鑰、令牌或OAuth 2.0進(jìn)行身份驗證
- 應(yīng)用基于角色的訪問控制（RBAC）進(jìn)行授權(quán)
9、不要維護(hù)狀態(tài)
REST API不應(yīng)在服務(wù)器上維護(hù)狀態(tài)，這是客戶端的責(zé)任。這很重要，因為它可以使API具備可緩存性、可擴展性，并使其與客戶端解耦。
例如，電子商務(wù)API可能使用cookie來維護(hù)購物車的狀態(tài)。然而，這種方法違反了RESTful API的關(guān)鍵原則：它們需要是無狀態(tài)的。
10、文檔化你的API
為你的API提供全面的文檔，包括端點細(xì)節(jié)、請求/響應(yīng)示例和使用指南。
建議：
- Swagger/OpenAPI文檔
- 基于Markdown的文檔（例如，使用Swagger UI或Redoc等工具）
