前言
在以前，一個網站的完成總是“all in one”，頁面，數據，渲染全部在服務端完成，這樣做的最大的弊端是後期維護，擴展極其痛苦，開發人員必須同時具備前後端知識。於是慢慢的後來興起了前後端分離的思想：
後端負責數據編造,而前端則負責數據渲染，前端靜態頁面調用指定api獲取到有固定格式的數據，再將數據展示出來，這樣呈現給用戶的就是一個”動態“的過程，而關於api這部分的設計則成了一個問題。如何設計出一個便於理解，容易使用的api則成了一個問題。
而所謂的restful就是用來規範我們的api的一種約束。
介紹
rest是REpresentational State Transfer三個單詞的縮寫，由Roy Fielding於2000年論文中提出，它代表着分佈式服務的架構風格。而如果想你的api被稱爲restful api，只要遵循其規定的約束即可。
rest設計原則
- 客戶端-服務器：通過將用戶UI與數據存儲分開，我們可以簡化服務器組件來提高跨多個平臺的用戶界面的可移植性並提高可伸縮性。它可以比表現成前後端分離的思想。
- 無狀態：從客戶端到服務器的每個請求都必須包含理解請求所需的所有信息，並且不能利用服務器上任何存儲的上下文。這表示你應該儘可能的避免使用session，由客戶端自己標識會話狀態。（token）
- 規範接口：REST接口約束定義：資源識別;請求動作; 響應信息; 它表示通過uri標出你要操作的資源，通過請求動作（http method）標識要執行的操作，通過返回的狀態碼來表示這次請求的執行結果。
- 可緩存：緩存約束要求將對請求的響應中的數據隱式或顯式標記爲可緩存或不可緩存。如果響應是可緩存的，則客戶端緩存有權重用該響應數據以用於以後的等效請求。 它表示get請求響應頭中應該表示有是否可緩存的頭（Cache-Control)
其中1，2，3約束最爲重要，其中1容易理解。接下來我們就談談無狀態和規範接口的原則。
uri規範
資源的描述構成了uri，它一般有以下約束：
1、使用名詞。如 user, student, class
http://api.example.com/class-management/students
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/
http://api.example.com/user-management/users/{id}
2、http method對應不同的請求動作（數據庫或者業務邏輯）
GET：查詢操作：
HTTP GET /devices?startIndex=0&size=20
HTTP GET /configurations?startIndex=0&size=20
HTTP GET /devices/{id}/configurations
HTTP GET /devices/{id}
POST：新增操作：
HTTP POST /device
PUT 更新操作（代表更新一個實體的所有屬性）
HTTP PUT /devices/{id}
PATCH 部分更新（代表更新一個屍體的部分屬性）由於有的瀏覽器兼容性問題，一般推薦使用put
HTTP PATCH /devices/{id}
DELETE 刪除操作
HTTP DELETE /devices/{id}
3、使用連字符（ - ）而不是（_）來提高URI的可讀性
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //更易讀
http://api.example.com/inventory_management/managed_entities/{id}/install_script_location //更容易出錯
4、在URI中使用小寫字母
http://api.example.org/my-folder/my-doc
5、不要使用文件擴展名 文件擴展名看起來很糟糕，不會增加任何優勢。刪除它們也會減少URI的長度。沒理由保留它們。
http://api.example.com/device-management/managed-devices.xml / 不要使用它 /
http://api.example.com/device-management/managed-devices / *這是正確的URI * /
6、使用查詢組件過濾URI集合
很多時候，我們會遇到需要根據某些特定資源屬性對需要排序，過濾或限制的資源集合的要求。爲此，請不要創建新的API - 而是在資源集合API中啓用排序，過濾和分頁功能，並將輸入參數作爲查詢參數傳遞。例如
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
7、不要在末尾使用/
作爲URI路徑中的最後一個字符，正斜槓（/）不會添加語義值，並可能導致混淆。最好完全放棄它們。
8、使用http狀態碼定義api執行結果
1xx：信息
通信傳輸協議級信息。
2xx：成功
表示客戶端的請求已成功接受。
3xx：重定向
表示客戶端必須執行一些其他操作才能完成其請求。
4xx：客戶端錯誤
此類錯誤狀態代碼指向客戶端。
5xx：服務器錯誤
服務器負責這些錯誤狀態代碼。
另外完整的更爲詳細的狀態碼此處不做贅述。一般簡化版本的api會使用200，400，500，其中400代表客戶端調用有誤，將錯誤信息放入response：
{
"error": "username.or.password.error"
}
9、api版本定義
當我們需要對現有的api接口升級的時候，因爲該api接口已經投入使用，所以新添加的業務可能無法保證兼容原來的邏輯，這個時候就需要新的接口，而這個接口一般表示對原來的接口的升級（不同版本），那版本怎麼定義呢？
- URI版本控制（推薦）
http://api.example.com/v1
http://apiv1.example.com - 使用自定義請求標頭進行版本控制
Accept-version：v1
Accept-version：v2 - 使用Accept header 進行版本控制
Accept:application / vnd.example.v1 + json
Accept:application / vnd.example + json; version = 1.0
無狀態
使REST API無狀態有一些非常顯着的優點：
1、無狀態通過將API部署到多個服務器，有助於將API擴展到數百萬併發用戶。任何服務器都可以處理任何請求，因爲沒有與會話相關的依賴。（集羣）
2、無狀態使得REST API不那麼複雜 - 可以刪除所有服務器端狀態同步邏輯。（刪除session，清理多餘空間）
3、無狀態API也很容易緩存。特定軟件可以通過查看該一個請求來決定是否緩存HTTP請求的結果。從先前的請求中獲得的狀態可能會影響這個請求的可緩存性，這並不存在任何不確定性。它提高了應用程序的性能。
4、服務器永遠不會忘記每個客戶端身份”，因爲客戶端會在每個請求中發送所有必要的信息。（攜帶token）
那麼無狀態又要怎麼實現呢？前面我們已經說了，服務端不應該再保存session會話，這個工作全部交由http請求去標識，而最常見的做法則是使用token。生成token可以考慮使用jwt，oauth。
總結
我們首先介紹rest服務背景，引出rest架構的介紹，最後重點介紹了rest api的約束設計。
本文轉自本文原創地址，我的博客：https://jsbintask.cn/2019/03/20/api/restful-api-best-practices/(食用效果最佳)，轉載請註明出處!