Web API在過去的幾年里非常盛行，因為它有着語法簡單、規范化和輕量級的優點，因為得到廣泛的推崇，很多過往的技術手段都慢慢轉換為使用Web API來開發。而Web API通常使用的設計方式是RESTful（Representational State Transfer，表述性狀態轉移），它使用了典型的HTTP方法，諸如GET、POST、PUT和DELETE來對資源進行管理和交互。
這里列出設計RESTful API的10個最佳實踐。
1.在API中使用名詞，而不是動詞。
在RESTful中，API描述的應該是資源，而不是動作，因此在API應使用名詞去描述資源，而不是動詞用動詞去描述動作。
|
RESOURCE
|
GET:READ
|
POST:CREATE
|
PUT:UPDATE
|
DELTE:DELETE
|
|---|---|---|---|---|
|
/cars |
返回一個car的列表 |
創建一個新的car |
更新car的信息 |
刪除所有的car |
|
/cars/yanggb |
返回指定的car |
Method not allowed(405) |
更新指定的car的信息 |
刪除指定的car |
而不是使用動詞，比如下面的API是不推薦的：
/getAllCars 獲取所有車輛 /createNewCar 創建新的車輛 /deleteAllRedCars 刪除所有紅色的車輛
2.GET方法和查詢參數不應該改變資源狀態。
GET方法的API應該是冪等的，即不應該改變資源的狀態，無論請求多少次，返回的結果都是一致的。
如果要改變資源的狀態，應該使用POST、PUT和DELETE方法。
3.使用名詞的復數形式。
不要混合使用名詞的單數和復數形式，而應該為所有的資源從一開始就保持使用復數形式。
/cars 替代 /car /users 替代 /user /products 替代 /product /settings 替代 /setting
4.為關系使用子資源。
假如資源連接到其他資源，則應該使用子資源的形式來設計API。
GET /cars/711/drivers 返回711車的驅動器列表
GET /cars/711/drivers/4 返回711車的#4驅動
5.使用HTTP頭決定序列化格式。
在客戶端和服務端都需要知道使用什么格式來進行通信，這個格式應該在HTTP頭中指定。
Content-Type：定義請求的格式。
Accept：定義允許的響應格式的列表。
6.使用HATEOAS。
HATEOAS（Hypermedia as the Engine of Application State）是REST架構風格中最復雜的約束，也是構建成熟REST服務的核心。它是一個指導原則，規定超文本鏈接應該被用於在API中創建更好的資源導航。
{ "id": 711, "manufacturer": "bmw", "model": "X5", "seats": 5, "drivers": [{ "id": "23", "name": "yanggb", "links": [{ "rel": "self", "href": "/api/v1/drivers/23" }] }] }
在上面的返回結果中，包含了超文本鏈接資源的信息。
7.為集合提供過濾、排序、字段選擇和分頁。
過濾：為所有字段或者查詢語句提供獨立的查詢參數。
GET /cars?color=red 返回紅色車的列表 GET /cars?seats<=2 返回兩座車的列表
排序：允許跨越多字段的正序或者倒序排列。
GET /cars?sort=-manufactorer,+model 返回排序的車輛列表
字段選擇：只列出需要的字段。一些情況下，只需要在列表中查詢幾個有標識意義的字段，並不需要從服務端把所有字段的值都請求出來，因此需要API支持選擇查詢字段的能力。這樣也可以在一定程度上提高網絡傳輸的性能與響應速度。
GET /cars?fields=manufacturer,model,id,color 返回需要的車輛信息字段的列表
分頁：使用offset和limit來獲取固定數量的資源結果，當其中一個參數沒有出現時，應該提供各自的默認值，比如默認取第一頁，或者默認取20條數據。
GET /cars?offset=10&limit=5 返回第10頁的5條車輛記錄列表 GET /cars?&limit=5 返回前5條車輛記錄列表 GET /cars?&offset=5 返回第5頁的車輛記錄列表（默認單頁數量）
8.版本化API。
確保強制實行API版本，並且不要發布一個沒有版本的API。使用簡單的序列數字，比如v1，避免使用2.5.0這樣的形式（點分隔符）。
/blog/api/v1
9.使用HTTP狀態碼處理錯誤。
忽略錯誤處理的API是很難使用的，簡單的返回500和調用堆棧是非常不友好的，同時這些錯誤信息在一定程度上來說也是無用的。
使用HTTP狀態碼
HTTP標准中提供了70多個狀態來描述返回值，但是我們並不需要用到其中的全部，只需要了解其中一些比較常用的就可以了。
200 – OK – 一切正常 201 – OK – 新資源已經被創建 204 – OK – 資源刪除成功 304 – 沒有變化，客戶端可以使用緩存數據 400 – Bad Request – 調用不合法，確切的錯誤應該在error payload中描述 401 – 未認證，調用需要用戶通過認證 403 – 不允許的，服務端正常解析和請求，但是調用被回絕或者不被允許 404 – 未找到，指定的資源不存在 422 – 不可指定的請求體 – 只有服務器不能處理實體時使用，比如圖像不能被格式化，或者重要字段丟失 500 – Internal Server Error – 標准服務端錯誤，API開發人員應該盡量避開這種錯誤
使用error payloads
所有的請求異常都應該被映射到error payloads中。
{ "errors": [{ "userMessage": "Sorry, the requested resource does not exist", "internalMessage": "No car found in the database", "code": 34, "more info":"http://www.yanggb.com/blog/api/v1/errors/12345" }] }
10.允許重寫HTTP方法。
一些代理只支持GET和POST方法。為了在這種限制下使用RESTful API（GET/POST/PUT/DELETE），則API需要重寫HTTP方法。
比如可以使用自定義的X-HTTP-Method-Override HTTP頭來重寫POST方法。
"感情實在是場無法掌控的事，沒有邏輯，沒有規律，更沒順理成章的必然。"