WebAPI在過去幾年裡非常的盛行，我們很多以往的技術手段都慢慢的轉換為使用WebAPI來開發，因為它的語法簡單規範化，以及輕量級等特點，這種方式收到了廣泛的推崇。

通常我們使用RESTFul（Representational State Transfer）的設計方式來設計Web api，這通常用來分離API結構了業務邏輯，它使用典型的HTTP方法，諸如GET,POST.DELETE,PUT來和資源進行互動。

以下是設計RESTful API的是個最佳實踐：

1. 使用名詞而不是動詞

為了易於理解，為資源使用下面的API結構：

不要使用動詞

/getAllCars
/createNewCar
/deleteAllRedCars

2. Get方法和查詢引數不應該改變資源狀態

使用Put,Post和Delete方法替代Get方法來改變資源狀態。不要使用Get來使狀態改變：

GET /users/711?activate or
GET /users/711/activate

3. 使用名詞的複數形式

不要混合使用單數和複數形式，而應該為所有資源一直保持使用複數形式：

/cars instead of /car
/users instead of /user
/products instead of /product
/settings instead of /setting

4. 為關係使用子資源

假如資源連線到其它資源，則使用子資源形式：

GET /cars/711/drivers/ Returns a list of drivers for car 711
GET /cars/711/drivers/4 Returns driver #4 for car 711

5. 使用HTTP頭決定序列化格式

在客戶端和服務端都需要知道使用什麼格式來進行通訊，這個格式應該在HTTP頭中指定:

• Content-Type：定義請求的格式；
• Accept ：定義允許的響應格式的列表

6. 使用HATEOAS

Hypermedia as the Engine of Application State是一個指導原則，它規定超文字連結應該被用於在API中建立更好的資源導航：

{
  "id": 711,
  "manufacturer": "bmw",
  "model": "X5",
  "seats": 5,
  "drivers": [
   {
    "id": "23",
    "name": "Stefan Jauker",
    "links": [
     {
     "rel": "self",
     "href": "/api/v1/drivers/23"
    }
   ]
  }
 ]
}

7. 為集合提供過濾、排序、欄位選擇以及分頁

過濾

為所有欄位或者查詢語句提供獨立的查詢引數：

GET /cars?color=red Returns a list of red cars
GET /cars?seats<=2 Returns a list of cars with a maximum of 2 seats

排序

允許跨越多欄位的正序或者倒序排列：

GET /cars?sort=-manufactorer,+model

欄位選擇

一些情況下，我們只需要在列表中查詢幾個有標識意義的欄位，我們不需要從服務端把所有欄位的值都請求出來，所以需要支援API選擇查詢欄位的能力，這也可以提到網路傳輸效能和速度：

GET /cars?fields=manufacturer,model,id,color

分頁

使用offset和limit來獲取固定數量的資源結果，當其中一個引數沒有出現時，應該提供各自的預設值，比如預設取第一頁，或者預設取20條資料：

GET /cars?offset=10&limit=5
GET /cars?&limit=5  //Get first five result
GET /cars?&offset=5  //Get default amount result offset 5

使用自定義的頭X-Total-Count發回給呼叫段實際的資源數量。

前一頁後一頁的連結也應該在HTTP頭連結中得到支援，遵從下文中的連結原則而不要構建你自己的頭：

Link: <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>; rel="next",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>; rel="last",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>; rel="first",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>; rel="prev",

8. 版本化你的API

確保強制實行API版本，並且不要釋出一個沒有版本的API，使用簡單的序列數字，避免使用2.5.0這樣的形式：

/blog/api/v1

9. 使用HTTP狀態碼處理錯誤

忽略錯誤處理的API是很難使用的，簡單的返回500和呼叫堆疊是非常不友好也非常無用的：

使用HTTP狀態碼

HTTP標準提供了70多個狀態碼來描述返回值，我們不需要完全用到他們，下文中列出10個使用率較高的：

200 – OK – 一切正常 201 – OK – 新資源已經被建立 204 – OK – 資源刪除成功

304 – 沒有變化，客戶端可以使用快取資料

400 – Bad Request – 呼叫不合法，確切的錯誤應該在error payload中描述，例如：“JSON 不合法 ” 401 – 未認證，呼叫需要使用者通過認證 403 – 不允許的，服務端正常解析和請求，但是呼叫被回絕或者不被允許 404 – 未找到，指定的資源不存在 422 – 不可指定的請求體 – 只有伺服器不能處理實體時使用，比如影象不能被格式化，或者重要欄位丟失。

500 – Internal Server Error – 標準服務端錯誤，API開發人員應該儘量避開這種錯誤

使用 error payloads

所有的異常都應該被對映到error payloads中，下文中的例子是一個json payload的模板：

{
  "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方法

一些代理只支援GET和POST方法，為了在這種限制下支援RESTful API，API需要重寫HTTP方法。

使用自定義的X-HTTP-Method-Override  HTTP頭來重寫POST方法。