**一、使用的好處** ***** 1. 看Url就知道要什么資源 2. 看http method就知道針對資源干什么 3. 看http status code就知道結果如何 **二、語法規范** ***** ### 2.1、RESTful是面向資源的（名詞） REST 通過 URI 暴露資源時，會強調不要在 URI 中出現動詞。比如： | 不符合REST的接口URI | 符合REST接口URI | 功能 | | --- | --- | --- | | GET /api/getDogs/{id} | GET /api/dogs/{id} | 獲取一個小狗狗 | | GET /api/getDogs | GET /api/dogs | 獲取所有小狗狗 | | GET /api/addDogs | POST /api/dogs | 添加一個小狗狗 | | GET /api/editDogs/{id} | PUT /api/dogs/{id} | 修改一個小狗狗 | | GET /api/deleteDogs/{id} | DELETE /api/dogs/{id} | 刪除一個小狗狗 | ### 2.2、用HTTP方法體現對資源的操作（動詞） * GET ： 獲取、讀取資源 * POST ： 添加資源 * PUT ： 修改資源 * DELETE ： 刪除資源  這四個動詞實際上就對應著增刪改查四個操作，這就利用了HTTP動詞來表示對資源的操作。 ### 2.3. HTTP狀態碼 通過HTTP狀態碼體現動作的結果,不要自定義 ``` 200 OK 400 Bad Request 500 Internal Server Error ``` 在 APP 與 API 的交互當中，其結果逃不出這三種狀態： * 所有事情都按預期正確執行完畢 - 成功 * APP 發生了一些錯誤 – 客戶端錯誤（如：校驗用戶輸入身份證，結果輸入的是軍官證，就是客戶端輸入錯誤） * API 發生了一些錯誤 – 服務器端錯誤（各種編碼bug或服務內部自己導致的異常） 這三種狀態與上面的狀態碼是一一對應的。如果你覺得這三種狀態，分類處理結果太寬泛，http-status code還有很多。建議還是要遵循KISS(Keep It Stupid and Simple)原則，上面的三種狀態碼完全可以覆蓋99%以上的場景。這三個狀態碼大家都記得住，而且非常常用，多了就不一定了。 ### 2.4. Get方法和查詢參數不應該改變數據 改變數據的事交給POST、PUT、DELETE ### 2.5. 使用復數名詞 /dogs 而不是 /dog ### 2.6. 復雜資源關系的表達 GET /cars/711/drivers/ 返回 使用過編號711汽車的所有司機 GET /cars/711/drivers/4 返回 使用過編號711汽車的4號司機 ### 2.7. 高級用法:HATEOAS **HATEOAS**:Hypermedia?as?the?Engine?of?Application?State 超媒體作為應用狀態的引擎。 RESTful API最好做到HATEOAS，**即返回結果中提供鏈接，連向其他API方法，使得用戶不查文檔，也知道下一步應該做什么**。比如，當用戶向api.example.com的根目錄發出請求，會得到這樣一個文檔。 ``` {"link": { "rel": "collection https://www.example.com/zoos", "href": "https://api.example.com/zoos", "title": "List of zoos", "type": "application/vnd.yourformat+json" }} ``` 上面代碼表示，文檔中有一個link屬性，用戶讀取這個屬性就知道下一步該調用什么API或者可以調用什么API了。 ### 2.8. 資源**過濾、排序、選擇和分頁**的表述  ### 2.9. 版本化你的API 強制性增加API版本聲明，不要發布無版本的API。如：/api/v1/blog **面向擴展開放，面向修改關閉**：也就是說一個版本的接口開發完成測試上線之后，我們一般不會對接口進行修改，如果有新的需求就開發新的接口進行功能擴展。這樣做的目的是：當你的新接口上線后，不會影響使用老接口的用戶。如果新接口目的是替換老接口，也不要在v1版本原接口上修改，而是開發v2版本接口，并聲明v1接口廢棄！ ## **附：** 關于HTTP RESTful風格API設計的更多例子，請大家參考：[http://httpbin.org/](http://httpbin.org/)