Web API 近幾年變得越來越火，而簡潔的 API 設計在多後端系統互動應用中也變得尤為重要。通常，會使用 RESTful API 來作為我們的 Web API 。本文介紹了幾種簡潔 RESTful API 設計的最佳實踐。
一、使用的名詞而不是動詞
使用名詞來定義接口，不應該使用動詞：
/getAllResources
/createNewResource
/deleteAllResources
二、GET 方法和查詢參數不能改變資源狀态
如果要改變資源的狀态，使用 PUT, POST 和 DELETE。下面是錯誤的用 GET 方法來修改 user 的狀态：
GET /users/711?activate 或
GET /users/711/activate
三、使用名詞複數
不要混淆名詞的單複數。保持簡單，隻用複數名詞定義所有資源。
/cars 代替 /car
/users 代替 /user
/products 代替 /product
/settings 代替 /setting
使用子資源來表達資源間的關系
GET /cars/711/drivers/ 傳回 711 号 car 的所有 driver 清單
GET /cars/711/drivers/4 傳回 711 号 car 的 4 号 driver
四、使用 HTTP header 來序列化格式
用戶端、服務端都需要知道互相之間的通訊格式。這些格式可以定義在 HTTP header 裡面：
- Content-Type：定義了請求格式
- Accept：定義了接收相應的格式清單
五、使用 HATEOAS 限制
HATEOAS（Hypermedia as the engine of application state）是 REST 架構風格中最複雜的限制，也是建構成熟 REST 服務的核心。它的重要性在于打破了用戶端和伺服器之間嚴格的契約，使得用戶端可以更加智能和自适應，而 REST 服務本身的演化和更新也變得更加容易。 在介紹 HATEOAS 之前，先介紹一下 Richardson 提出的 REST 成熟度模型。該模型把 REST 服務按照成熟度劃分成 4 個層次：
- 第一個層次（Level 0）的 Web 服務隻是使用 HTTP 作為傳輸方式，實際上隻是遠端方法調用（RPC）的一種具體形式。SOAP 和 XML-RPC 都屬于此類。
- 第二個層次（Level 1）的 Web 服務引入了資源的概念。每個資源有對應的辨別符和表達。
- 第三個層次（Level 2）的 Web 服務使用不同的 HTTP 方法來進行不同的操作，并且使用 HTTP 狀态碼來表示不同的結果。如 HTTP GET 方法來擷取資源，HTTP DELETE 方法來删除資源。
- 第四個層次（Level 3）的 Web 服務使用 HATEOAS。在資源的表達中包含了連結資訊。用戶端可以根據連結來發現可以執行的動作。
從上述 REST 成熟度模型中可以看到，使用 HATEOAS 的 REST 服務是成熟度最高的，也是推薦的做法。對于不使用 HATEOAS 的 REST 服務，用戶端和伺服器的實作之間是緊密耦合的。用戶端需要根據伺服器提供的相關文檔來了解所暴露的資源和對應的操作。當伺服器發生了變化時，如修改了資源的 URI，用戶端也需要進行相應的修改。而使用 HATEOAS 的 REST 服務中，用戶端可以通過伺服器提供的資源的表達來智能地發現可以執行的操作。當伺服器發生了變化時，用戶端并不需要做出修改，因為資源的 URI 和其他資訊都是動态發現的。
下面是一個 HATEOAS 的例子：
{
"id": 711,
"manufacturer": "bmw",
"model": "X5",
"seats": 5,
"drivers": [
{
"id": "23",
"name": "Stefan Jauker",
"links": [
{
"rel": "self",
"href": "/api/v1/drivers/23"
}
]
}
]
}
六、提供過濾、排序、字段選擇、分頁
過濾：
GET /cars?color=red
GET /cars?seats<=2
排序：
GET /cars?sort=-manufactorer,+model
字段選擇:
GET /cars?fields=manufacturer,model,id,color
分頁:
GET /cars?offset=10&limit=5
七、API 版本化
版本号使用簡單的序号，并避免點符号，如2.5等。正确用法如下：
/blog/api/v1
八、充分使用 HTTP 狀态碼來處理錯誤
HTTP狀态碼（HTTP Status Code）是用以表示網頁伺服器 HTTP 響應狀态的3位數字代碼。它由 RFC 2616 規範定義的，并得到 RFC 2518、RFC 2817、RFC 2295、RFC 2774、RFC 4918 等規範的擴充。
在設計 API 處理錯誤時，應該充分使用 HTTP 狀态碼，而不是簡單的抛出個 “500 – Internal Server Error（内部伺服器錯誤）”
所有的異常都應該有個錯誤的 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"
}
]