項目資源的URL應該如何設計?用名詞複數還是用名詞單數?一個資源需要多少個URL?用哪種HTTP方法來創建一個新的資源?可選參數應該放在哪裏?那些不涉及資源操作的URL呢?實現分頁和版本控制的最好方法是什麼?因爲有太多的疑問,設計RESTful API變得很棘手。在這篇文章中,我們來看一下RESTful API設計,並給出一個最佳實踐方案。
每個資源使用兩個URL
資源集合用一個URL,具體某個資源用一個URL:
/employees #資源集合的URL
/employees/56 #具體某個資源的URL
用名詞代替動詞表示資源
這讓你的API更簡潔,URL數目更少。不要這麼設計:
/getAllEmployees
/getAllExternalEmployees
/createEmployee
/updateEmployee
更好的設計:
GET /employees
GET /employees?state=external
POST /employees
PUT /employees/56
用HTTP方法操作資源
使用URL指定你要用的資源。使用HTTP方法來指定怎麼處理這個資源。使用四種HTTP方法POST,GET,PUT,DELETE可以提供CRUD功能(創建,獲取,更新,刪除)。
獲取:使用GET方法獲取資源。GET請求從不改變資源的狀態。無副作用。GET方法是冪等的。GET方法具有隻讀的含義。因此,你可以完美的使用緩存。
創建:使用POST創建新的資源。
更新:使用PUT更新現有資源。
刪除:使用DELETE刪除現有資源。
2個URL乘以4個HTTP方法就是一組很好的功能。看看這個表格:
POST(創建) GET(讀取) PUT(更新) DELETE(刪除)
/employees 創建一個新員工 列出所有員工 批量更新員工信息 刪除所有員工
/employees/56 (錯誤) 獲取56號員工的信息 更新56號員工的信息 刪除56號員工
對資源集合的URL使用POST方法,創建新資源
創建一個新資源的時,客戶端與服務器是怎麼交互的呢?
在資源集合URL上使用POST來創建新的資源過程:
客戶端向資源集合URL/employees發送POST請求。HTTP body 包含新資源的屬性 “Albert Stark”。
RESTful Web服務器爲新員工生成ID,在其內部模型中創建員工,並向客戶端發送響應。這個響應的HTTP頭部包含一個Location字段,指示創建資源可訪問的URL。
對具體資源的URL使用PUT方法,來更新資源
使用PUT更新已有資源:
客戶端向具體資源的URL發送PUT請求/employee/21。請求的HTTP body中包含要更新的屬性值(21號員工的新名稱“Bruce Wayne”)。
REST服務器更新ID爲21的員工名稱,並使用HTTP狀態碼200表示更改成功。
推薦用複數名詞
推薦:
/employees
/employees/21
不推薦:
/employee
/employee/21
事實上,這是個人愛好問題,但複數形式更爲常見。此外,在資源集合URL上用GET方法,它更直觀,特別是GET /employees?state=external、POST /employees、PUT /employees/56。但最重要的是:避免複數和單數名詞混合使用,這顯得非常混亂且容易出錯。
對可選的、複雜的參數,使用查詢字符串(?)。
不推薦做法:
GET /employees
GET /externalEmployees
GET /internalEmployees
GET /internalAndSeniorEmployees
爲了讓你的URL更小、更簡潔。爲資源設置一個基本URL,將可選的、複雜的參數用查詢字符串表示。
GET /employees?state=internal&maturity=senior
使用HTTP狀態碼
RESTful Web服務應使用合適的HTTP狀態碼來響應客戶端請求
2xx - 成功 - 一切都很好
4xx - 客戶端錯誤 - 如果客戶端發生錯誤(例如客戶端發送無效請求或未被授權)
5xx – 服務器錯誤 - 如果服務器發生錯誤(例如,嘗試處理請求時出錯)
參考維基百科上的HTTP狀態代碼。但是,其中的大部分HTTP狀態碼都不會被用到,只會用其中的一小部分。通常會用到一下幾個:
2xx:成功 3xx:重定向 4xx:客戶端錯誤 5xx:服務器錯誤
200 成功 301 永久重定向 400 錯誤請求 500 內部服務器錯誤
201 創建 304 資源未修改 401未授權
403 禁止
404 未找到
返回有用的錯誤提示
除了合適的狀態碼之外,還應該在HTTP響應正文中提供有用的錯誤提示和詳細的描述。這是一個例子。請求:
GET /employees?state=super
響應:
// 400 Bad Request
{
"message": "You submitted an invalid state. Valid state values are 'internal' or 'external'",
"errorCode": 352,
"additionalInformation" :
"http://www.domain.com/rest/errorcode/352"
}
使用小駝峯命名法
使用小駝峯命名法作爲屬性標識符。
{ “yearOfBirth”: 1982 }
不要使用下劃線(year_of_birth)或大駝峯命名法(YearOfBirth)。通常,RESTful Web服務將被JavaScript編寫的客戶端使用。客戶端會將JSON響應轉換爲JavaScript對象(通過調用var person = JSON.parse(response)),然後調用其屬性。因此,最好遵循JavaScript代碼通用規範。
對比:
person.year_of_birth // 不推薦,違反JavaScript代碼通用規範
person.YearOfBirth // 不推薦,JavaScript構造方法命名
person.yearOfBirth // 推薦
在URL中強制加入版本號
從始至終,都使用版本號發佈您的RESTful API。將版本號放在URL中以是必需的。如果您有不兼容和破壞性的更改,版本號將讓你能更容易的發佈API。發佈新API時,只需在增加版本號中的數字。這樣的話,客戶端可以自如的遷移到新API,不會因調用完全不同的新API而陷入困境。 使用直觀的 “v” 前綴來表示後面的數字是版本號。
/v1/employees
你不需要使用次級版本號(“v1.2”),因爲你不應該頻繁的去發佈API版本。
提供分頁信息
一次性返回數據庫所有資源不是一個好主意。因此,需要提供分頁機制。通常使用數據庫中衆所周知的參數offset和limit。
/employees?offset=30&limit=15 #返回30 到 45的員工
如果客戶端沒有傳這些參數,則應使用默認值。通常默認值是offset = 0和limit = 10。如果數據庫檢索很慢,應當減小limit值。
/employees #返回0 到 10的員工
此外,如果您使用分頁,客戶端需要知道資源總數。例:請求:
GET /employees
響應:
{
"offset": 0,
"limit": 10,
"total": 3465,
"employees": [
//...
]
}
非資源請求用動詞
有時API調用並不涉及資源(如計算,翻譯或轉換)。例:
GET /translate?from=de_DE&to=en_US&text=Hallo
GET /calculate?para2=23¶2=432
在這種情況下,API響應不會返回任何資源。而是執行一個操作並將結果返回給客戶端。因此,您應該在URL中使用動詞而不是名詞,來清楚的區分資源請求和非資源請求。
考慮特定資源搜索和跨資源搜索
提供對特定資源的搜索很容易。只需使用相應的資源集合URL,並將搜索字符串附加到查詢參數中即可。
GET /employees?query=Paul
如果要對所有資源提供全局搜索,則需要用其他方法。前文提到,對於非資源請求URL,使用動詞而不是名詞。因此,您的搜索網址可能如下所示:
GET /search?query=Paul //返回 employees, customers, suppliers 等等.
在響應參數中添加瀏覽其它API的鏈接
理想情況下,不會讓客戶端自己構造使用REST API的URL。讓我們思考一個例子。
客戶端想要訪問員工的薪酬表。爲此,他必須知道他可以通過在員工URL(例如/employees/21/salaryStatements)中附加字符串“salaryStatements”來訪問薪酬表。這個字符串連接很容易出錯,且難以維護。如果你更改了訪問薪水錶的REST API的方式(例如變成了/employees/21/salary-statement或/employees/21/paySlips),所有客戶端都將中斷。
更好的方案是在響應參數中添加一個links字段,讓客戶端可以自動變更。
請求:
GET /employees/
響應:
//...
{
"id":1,
"name":"Paul",
"links": [
{
"rel": "salary",
"href": "/employees/1/salaryStatements"
}
]
},
//...
如果客戶端完全依靠links中的字段獲得薪資表,你更改了API,客戶端將始終獲得一個有效的URL(只要你更改了link字段,請求的URL會自動更改),不會中斷。另一個好處是,你的API變得可以自我描述,需要寫的文檔更少。
在分頁時,您還可以添加獲取下一頁或上一頁的鏈接示例。只需提供適當的偏移和限制的鏈接示例。
GET /employees?offset=20&limit=10
{
"offset": 20,
"limit": 10,
"total": 3465,
"employees": [
//...
],
"links": [
{
"rel": "nextPage",
"href": "/employees?offset=30&limit=10"
},
{
"rel": "previousPage",
"href": "/employees?offset=10&limit=10"
}
]
}