最近寫了幾個有關RESTful的API相關內容，也談談對常見問題的自己的理解。 1.什麼是RESTful 詳情可以看 "http://www.ruanyifeng.com/blog/2011/09/restful.html" 。 簡單可以這麼理解，使用 去代表資源，使用HTTP VERB（GET P ...
最近寫了幾個有關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？
乍看一眼，覺得好像都差不多，沒內容和沒找到反正都是沒有。但深入想想，還是有很大的區別的。
- 404返回的更傾向於表述不存在的性質，而204返回表述沒有內容，也就是存在，但是沒有內容。
- 4xx返回表述大體是請求有問題，而2xx返回表述大體是請求沒有問題。
所以，對於上面的問題，這麼理解，如果homework是已經創建的資源，但是內容為空，那麼返回204是可以的，但是如果homework這個東西就不存在，那麼應該返回404。
個人認為直接返回200，攜帶對應的空內容會比204要對調用方更加友好，至少和有數據的情況是一樣處理。
9.寫給前端
有很多前端同學需要伺服器返回固定的成功信息（比如200）或者錯誤信息（比如400）。但HTTP CODE很多，一個一個判斷效率很低，好在HTTP CODE是分類的，比如2xx大體是OK的，4xx都是有問題的。可以通過CODE / 100 == 2之類的方法去大體確定返回的狀態 。
