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

之類的方法去大體确定傳回的狀态 。

除非特殊說明，本作品由podolski創作，采用知識共享署名 4.0 國際許可協定進行許可。歡迎轉載，轉載請保留原文連結~喜歡的觀衆老爺們可以點下關注或者推薦~