關於restful API url整理

 

每一個資源使用兩個URL

資源集合用一個URL，具體某個資源用一個URL：

1. /employees         #資源集合的URL

2. /employees/56      #具體某個資源的URL

用名詞代替動詞表示資源

這讓你的API更簡潔，URL數目更少。不要這麼設計：

1. /getAllEmployees

2. /getAllExternalEmployees

3. /createEmployee

4. /updateEmployee

更好的設計：

1. GET /employees

2. GET /employees?state=external

3. POST /employees

4. 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來建立新的資源過程：

1. 客戶端向資源集合URL /employees發送POST請求。HTTP body 包含新資源的屬性 「Albert Stark」。

2. RESTful Web服務器爲新員工生成ID，在其內部模型中建立員工，並向客戶端發送響應。這個響應的HTTP頭部包含一個Location字段，指示建立資源可訪問的URL。

對具體資源的URL使用PUT方法，來更新資源

使用PUT更新已有資源：

1. 客戶端向具體資源的URL發送PUT請求 /employee/21。請求的HTTP body中包含要更新的屬性值（21號員工的新名稱「Bruce Wayne」）。

2. REST服務器更新ID爲21的員工名稱，並使用HTTP狀態碼200表示更改爲功。

推薦用複數名詞

推薦：

1. /employees

2. /employees/21

不推薦：

1. /employee

2. /employee/21

事實上，這是我的愛好問題，但複數形式更爲常見。此外，在資源集合URL上用GET方法，它更直觀，特別是 GET/employees?state=external、 POST/employees、 PUT/employees/56。但最重要的是：避免複數和單數名詞混合使用，這顯得很是混亂且容易出錯。

對可選的、複雜的參數，使用查詢字符串（？）。

不推薦作法：

1. GET /employees

2. GET /externalEmployees

3. GET /internalEmployees

4. GET /internalAndSeniorEmployees

爲了讓你的URL更小、更簡潔。爲資源設置一個基本URL，將可選的、複雜的參數用查詢字符串表示。

1. 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響應正文中提供有用的錯誤提示和詳細的描述。這是一個例子。 請求：

1. GET /employees?state=super

響應：

1. // 400 Bad Request

2. {

3.    "message": "You submitted an invalid state. Valid state values are 'internal' or 'external'",

4.    "errorCode": 352,

5.    "additionalInformation" :

6.    "http://www.domain.com/rest/errorcode/352"

7. }

使用小駝峯命名法

使用小駝峯命名法做爲屬性標識符。

1. { "yearOfBirth": 1982 }

不要使用下劃線（ year_of_birth）或大駝峯命名法（ YearOfBirth）。一般，RESTful Web服務將被JavaScript編寫的客戶端使用。客戶端會將JSON響應轉換爲JavaScript對象（經過調用 varperson=JSON.parse(response)），而後調用其屬性。所以，最好遵循JavaScript代碼通用規範。
對比：

1. person.year_of_birth // 不推薦，違反JavaScript代碼通用規範

2. person.YearOfBirth // 不推薦，JavaScript構造方法命名

3. person.yearOfBirth // 推薦

在URL中強制加入版本號

從始至終，都使用版本號發佈您的RESTful API。將版本號放在URL中以是必需的。若是您有不兼容和破壞性的更改，版本號將讓你能更容易的發佈API。發佈新API時，只需在增長版本號中的數字。這樣的話，客戶端能夠自如的遷移到新API，不會因調用徹底不一樣的新API而陷入困境。
使用直觀的 「v」 前綴來表示後面的數字是版本號。

1. /v1/employees

你不須要使用次級版本號（「v1.2」），由於你不該該頻繁的去發佈API版本。

提供分頁信息

一次性返回數據庫全部資源不是一個好主意。所以，須要提供分頁機制。一般使用數據庫中衆所周知的參數offset和limit。

1. /employees?offset=30&limit=15       #返回30 到 45的員工

若是客戶端沒有傳這些參數，則應使用默認值。一般默認值是 offset=0和 limit=10。若是數據庫檢索很慢，應當減少 limit值。

1. /employees       #返回0 到 10的員工

此外，若是您使用分頁，客戶端須要知道資源總數。例： 請求：

1. GET /employees

響應：

1. {

2.  "offset": 0,

3.  "limit": 10,

4.  "total": 3465,

5.  "employees": [

6.    //...

7.  ]

8. }

非資源請求用動詞

有時API調用並不涉及資源（如計算，翻譯或轉換）。例：

1. GET /translate?from=de_DE&to=en_US&text=Hallo

2. GET /calculate?para2=23&para2=432

在這種狀況下，API響應不會返回任何資源。而是執行一個操做並將結果返回給客戶端。所以，您應該在URL中使用動詞而不是名詞，來清楚的區分資源請求和非資源請求。

考慮特定資源搜索和跨資源搜索

提供對特定資源的搜索很容易。只需使用相應的資源集合URL，並將搜索字符串附加到查詢參數中便可。

1. GET /employees?query=Paul

若是要對全部資源提供全局搜索，則須要用其餘方法。前文提到，對於非資源請求URL，使用動詞而不是名詞。所以，您的搜索網址可能以下所示：

1. 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字段，讓客戶端能夠自動變動。
請求：

1. GET /employees/

響應：

1. //...

2.   {

3.      "id":1,

4.      "name":"Paul",

5.      "links": [

6.         {

7.            "rel": "salary",

8.            "href": "/employees/1/salaryStatements"

9.         }

10.      ]

11.   },

12. //...

若是客戶端徹底依靠 links中的字段得到薪資表，你更改了API，客戶端將始終得到一個有效的URL（只要你更改了 link字段，請求的URL會自動更改），不會中斷。另外一個好處是，你的API變得能夠自我描述，須要寫的文檔更少。
在分頁時，您還能夠添加獲取下一頁或上一頁的連接示例。只需提供適當的偏移和限制的連接示例。

1. GET /employees?offset=20&limit=10

1. {

2.  "offset": 20,

3.  "limit": 10,

4.  "total": 3465,

5.  "employees": [

6.    //...

7.  ],

8.  "links": [

9.     {

10.        "rel": "nextPage",

11.        "href": "/employees?offset=30&limit=10"

12.     },

13.     {

14.        "rel": "previousPage",

15.        "href": "/employees?offset=10&limit=10"

16.     }

17.  ]

18. }