作者：JDON
連結：https://www.jdon.com/soa/10-best-practices-for-better-restful-api.html
Web API已經在最近幾年變成重要的話題，一個幹淨的API設計對于後端系統是非常重要的。
通常我們為Web API使用RESTful設計，REST概念分離了API結構和邏輯資源，通過Http方法GET, DELETE, POST 和 PUT來操作資源。
下面是進行RESTful Web API十個最佳實踐，能為你提供一個良好的API設計風格。
1.使用名詞而不是動詞
不要使用：
/getAllCars
/createNewCar
/deleteAllRedCars
2.Get方法和查詢參數不應該涉及狀态改變
使用PUT, POST 和DELETE 方法 而不是 GET 方法來改變狀态，不要使用GET 進行狀态改變:
GET /users/711?activate
GET /users/711/activate
3.使用複數名詞
不要混淆名詞單數和複數，為了保持簡單，隻對所有資源使用複數。
/cars 而不是 /car
/users 而不是 /user
/products 而不是 /product
/settings 而部署 /setting
4. 使用子資源表達關系
如果一個資源與另外一個資源有關系，使用子資源：
GET /cars/711/drivers/ 傳回 car 711的所有司機
GET /cars/711/drivers/4 傳回 car 711的4号司機
5.使用Http頭聲明序列化格式
在用戶端和服務端，雙方都要知道通訊的格式，格式在HTTP-Header中指定
Content-Type 定義請求格式
Accept 定義系列可接受的響應格式
6.使用HATEOAS
Hypermedia as the Engine of Application State 超媒體作為應用狀态的引擎，超文本連結可以建立更好的文本浏覽：
{
"id": 711,
"manufacturer": "bmw",
"model": "X5",
"seats": 5,
"drivers": [
{
"id": "23",
"name": "Stefan Jauker",
"links": [
{
"rel": "self",
"href": "/api/v1/drivers/23"
}
]
}
]
}
注意href指向下一個URL
7.為集合提供過濾 排序 選擇和分頁等功能
Filtering過濾:
使用唯一的查詢參數進行過濾：
GET /cars?color=red 傳回紅色的cars
GET /cars?seats<=2 傳回小于兩座位的cars集合
Sorting排序:
允許針對多個字段排序
GET /cars?sort=-manufactorer,+model
這是傳回根據生産者降序和模型升序排列的car集合
Field selection
移動端能夠顯示其中一些字段，它們其實不需要一個資源的所有字段，給API消費者一個選擇字段的能力，這會降低網絡流量，提高API可用性。
GET /cars?fields=manufacturer,model,id,color
Paging分頁
使用 limit 和offset.實作分頁，預設limit=20 和offset=0；
GET /cars?offset=10&limit=5
為了将總數發給用戶端，使用訂制的HTTP頭： X-Total-Count.
連結到下一頁或上一頁可以在HTTP頭的link規定，遵循Link規定:
Link: ; rel="next",; rel="last",; rel="first",; rel="prev",
8.版本化你的API
使得API版本變得強制性，不要釋出無版本的API，使用簡單數字，避免小數點如2.5.
一般在Url後面使用?v
/blog/api/v1
9. 使用Http狀态碼處理錯誤
如果你的API沒有錯誤處理是很難的，隻是傳回500和出錯堆棧不一定有用
Http狀态碼提供70個出錯，我們隻要使用10個左右：
200 – OK – 一切正常
201 – OK – 新的資源已經成功建立
204 – OK – 資源已經成功擅長
304 – Not Modified – 用戶端使用緩存資料
400 – Bad Request – 請求無效，需要附加細節解釋如 "JSON無效"
401 – Unauthorized – 請求需要使用者驗證
403 – Forbidden – 伺服器已經了解了請求，但是拒絕服務或這種請求的通路是不允許的。
404 – Not found – 沒有發現該資源
422 – Unprocessable Entity – 隻有伺服器不能處理實體時使用，比如圖像不能被格式化，或者重要字段丢失。
500 – Internal Server Error – API開發者應該避免這種錯誤。
使用詳細的錯誤包裝錯誤：
{
"errors": [
{
"userMessage": "Sorry, the requested resource does not exist",
"internalMessage": "No car found in the database",
"code": 34,
"more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"
}
]
}
10.允許覆寫http方法
一些代理隻支援POST 和 GET方法， 為了使用這些有限方法支援RESTful API，需要一種辦法覆寫http原來的方法。
使用訂制的HTTP頭 X-HTTP-Method-Override 來覆寫POST 方法.