RESTful設計中的常見疑問

最近寫了幾個有關RESTful的API相關內容，也談談對常見問題的本身的理解。

1.什麼是RESTful

詳情能夠看http://www.ruanyifeng.com/blog/2011/09/restful.html。

簡單能夠這麼理解，使用URI去表明資源，使用HTTP VERB（GET PUT等）對資源的操做。

2.爲何要用RESTful

使用RESTful，優勢有不少，也方便不一樣的請求方去請求數據。列舉兩個：

• HTTP方法語義都很明確，使用GET去得到數據，使用DELETE去刪除數據。
• 返回值也是很明確的HTTP RESPONSE，200就是執行成功，400就是請求錯誤。

那是否是每個API都須要使用REST風格呢？我以爲不是，這要看團隊、項目而定，沒必要一味強求。

3.在URI資源地址中使用v1之類的版本號符不符合RESTful？

這個涉及到RESTful的版本管理，常見的方法有這麼幾種。

URL Path

/api/v1/helloworld

不少公開的API地址裏面，都帶有version信息，若是非要去扣符不符合RESTful，估計要吵起來。可是這個方式很便捷、明確，調用方一看就明白，也沒有額外的工做量去作。不過缺點也很明顯，因爲已經限定死了版本號在URI中，沒法實現同一個URI地址版本的靈活切換，也不能指定默認版本。

Query String

/api/helloworld?api-version=1.0

這個方式沒有改變URI自己，可是須要調用方去額外處理Query string，不過好在這個能夠指定默認的。

Media Types

POST api/helloworld HTTP/1.1
host: localhost
content-type: text/plain;v=2.0
content-length: 12

Hello there!

在Content-Type裏面添加v=x.x的版本號也是一個不錯的選擇，能夠實現QueryString相似的功能。

有一些現成的庫能夠幫助咱們實現上面的Versioning方法，常見的是aspnet-api-versioning

4.什麼是安全性？

不管請求多少次，服務器的狀態（資源）都不會改變，那麼這個方法就是安全的。

GET HEAD都應該設計成安全的。

5.什麼是冪等性？

不管對資源操做多少次，服務器資源結果老是同樣的，那麼這個方法就是冪等的。注意這裏的說法，是服務器的資源結果是同樣的，不表明請求的返回結果是同樣的。好比DELETE請求，它是冪等的，可是刪除一個資源不少次的狀況（屢次執行DELETE api/student/1，第一次返回成功，第二次返回失敗，可是不影響服務器上對應的記錄已經刪除的狀態。

GET、HEAD、PUT和DELETE請求都應該設計成是冪等的。

6.新增數據用POST仍是PUT？

資源新增能夠用POST也能夠用PUT，可是設計上有幾個區別。

冪等性

PUT是冪等的，POST不是，若是設計上須要不該用冪等性，那麼使用POST。好比POST計數器的應用，每次POST，計數器都增加1。

請求目標

POST通常請求的是資源集合，而PUT通常請求是一個具體的資源。

PUT /students/{id}
POST /students

這也意味着，語義上，POST是請求在集合中新增資源。

主動權

• 若是id不是由調用方生成的狀況下，須要指定的資源ID的PUT方法就很差實現了。這種狀況，使用POST到資源更合理，主動權在服務器方，服務器建立資源以後，返回201攜帶新生成的對象URI。
• 若是id是由調用方生成的狀況下（好比一些硬件設備產生的數據），使用POST和PUT均可以，可是PUT有冪等性，顯得更加明確，這種時候我通常選擇使用PUT。

覆蓋

PUT語義是要求覆蓋的，若是數據已經存在，就必須覆蓋。POST的沒有這個要求，能夠有別的行爲。

7.修改數據應該使用PUT仍是PATCH？

不必定，要看狀況。PUT是覆蓋性的修改，而PATCH是追加性的修改。

• 使用PUT的時候，須要將數據完整返回，若是有的字段沒有賦值，那麼將保持爲默認值。
• PUT是冪等的，PATCH不是，所以屢次執行PUT請求，結果是同樣的；執行PATCH有可能不同。

{
"value": 
    {
        "id": "235314",
        "deviceId": "123",
        "type": "低溫"
    }
}

若是發送的數據只含有deviceId，執行PUT以後，資源變成：

{
"value": 
    {
        "id": "235314",
        "deviceId": "111"
    }
}

執行PATCH，資源變成：

{
"value": 
    {
        "id": "235314",
        "deviceId": "111",
        "type": "低溫"
    }
}

8.沒有數據返回204仍是404？

問題：

若是請求一個這樣的資源

GET api/sutudents/homework

在沒有homework的狀況下應該返回HTTP 204 NoContent仍是返回HTTP 404 NotFound？

乍看一眼，以爲好像都差很少，沒內容和沒找到反正都是沒有。但深刻想一想，仍是有很大的區別的。

1. 404返回的更傾向於表述不存在的性質，而204返回表述沒有內容，也就是存在，可是沒有內容。
2. 4xx返回表述大致是請求有問題，而2xx返回表述大致是請求沒有問題。

因此，對於上面的問題，這麼理解，若是homework是已經建立的資源，可是內容爲空，那麼返回204是能夠的，可是若是homework這個東西就不存在，那麼應該返回404。

我的認爲直接返回200，攜帶對應的空內容會比204要對調用方更加友好，至少和有數據的狀況是同樣處理。

9.寫給前端

有不少前端同窗須要服務器返回固定的成功信息（好比200）或者錯誤信息（好比400）。但HTTP CODE不少，一個一個判斷效率很低，好在HTTP CODE是分類的，好比2xx大致是OK的，4xx都是有問題的。能夠經過CODE / 100 == 2之類的方法去大致肯定返回的狀態 。