REST接口設計規範總結

URI格式規範
URI中儘可能使用連字符」-「代替下劃線」_」的使用
URI中統一使用小寫字母
URI中不要包含文件(腳本)的擴展名

URI命名規範
文檔(Document)類型的資源用名詞(短語)單數命名
集合(Collection)類型的資源用名詞(短語)複數命名
倉庫(Store)類型的資源用名詞(短語)複數命名
控制器(Controller)類型的資源用動詞(短語)命名
URI中有些字段能夠是變量，在實際使用中能夠按需替換
CRUD的操做不要體如今URI中，HTTP協議中的操做符已經對CRUD作了映射。

HTTP請求方法的使用
GET方法用來獲取資源
PUT方法可用來新增/更新Store類型的資源
PUT方法可用來更新一個資源的所有屬性，使用時傳遞全部屬性的值，即便有的值沒有改變
PATCH方法更新資源的部分屬性。由於 PATCH 比較新，並且規範比較複雜，因此真正實現的比較少，通常都是用 POST 替代
POST方法可用來建立一個資源
POST方法可用來觸發執行一個Controller類型資源
DELETE方法用於刪除資源

HTTP響應狀態碼的使用
200 (「OK」) 用於通常性的成功返回，不可用於請求錯誤返回
201 (「Created」) 資源被建立
202 (「Accepted」) 用於Controller控制類資源異步處理的返回，僅表示請求已經收到。對於耗時比較久的處理，通常用異步處理來完成。
204 (「No Content」) 此狀態可能會出如今PUT、POST、DELETE的請求中，通常表示資源存在，但消息體中不會返回任何資源相關的狀態或信息。
301 (「Moved Permanently」) 資源的URI被轉移，須要使用新的URI訪問
302 (「Found」) 不推薦使用，此代碼在HTTP1.1協議中被303/307替代。咱們目前對302的使用和最初HTTP1.0定義的語意是有出入的，應該只有在GET/HEAD方法下，客戶端才能根據Location執行自動跳轉，而咱們目前的客戶端基本上是不會判斷原請求方法的，無條件的執行臨時重定向
303 (「See Other」) 返回一個資源地址URI的引用，但不強制要求客戶端獲取該地址的狀態(訪問該地址)
304 (「Not Modified」) 有一些相似於204狀態，服務器端的資源與客戶端最近訪問的資源版本一致，並沒有修改，不返回資源消息體。能夠用來下降服務端的壓力
307 (「Temporary Redirect」) 目前URI不能提供當前請求的服務，臨時性重定向到另一個URI。在HTTP1.1中307是用來替代早期HTTP1.0中使用不當的302
400 (「Bad Request」) 用於客戶端通常性錯誤返回, 在其它4xx錯誤之外的錯誤，也可使用400，具體錯誤信息能夠放在body中
401 (「Unauthorized」) 在訪問一個須要驗證的資源時，驗證錯誤
403 (「Forbidden」) 通常用於非驗證性資源訪問被禁止，例如對於某些客戶端只開放部分API的訪問權限，而另一些API可能沒法訪問時，能夠給予403狀態
404 (「Not Found」) 找不到URI對應的資源
405 (「Method Not Allowed」) HTTP的方法不支持，例如某些只讀資源，可能不支持POST/DELETE。但405的響應header中必須聲明該URI所支持的方法
406 (「Not Acceptable」) 客戶端所請求的資源數據格式類型不被支持，例如客戶端請求數據格式爲application/xml，但服務器端只支持application/json
409 (「Conflict」) 資源狀態衝突，例如客戶端嘗試刪除一個非空的Store資源
412 (「Precondition Failed」) 用於有條件的操做不被知足時
415 (「Unsupported Media Type」) 客戶所支持的數據類型，服務端沒法知足
429 (「Too Many Requests」) 客戶端在規定的時間裏發送了太多請求，在進行限流的時候會用到
500 (「Internal Server Error」) 服務器端的接口錯誤，此錯誤於客戶端無關

HTTP Headers
Content-Type 標示body的數據格式
Content-Length body 數據體的大小，客戶端能夠根據此標示檢驗讀取到的數據是否完整，也能夠經過Header判斷是否須要下載可能較大的數據體
Last-Modified 用於服務器端的響應，是一個資源最後被修改的時間戳，客戶端(緩存)能夠根據此信息判斷是否須要從新獲取該資源
ETag 服務器端資源版本的標示，客戶端(緩存)能夠根據此信息判斷是否須要從新獲取該資源，須要注意的是，ETag若是經過服務器隨機生成，可能會存在多個主機對同一個資源產生不一樣ETag的問題
Store類型的資源要支持有條件的PUT請求
Location 在響應header中使用，通常爲客戶端感興趣的資源URI,例如在成功建立一個資源後，咱們能夠把新的資源URI放在Location中，若是是一個異步建立資源的請求，接口在響應202 (「Accepted」)的同時能夠給予客戶端一個異步狀態查詢的地址
Cache-Control, Expires, Date 經過緩存機制提高接口響應性能,同時根據實際須要也能夠禁止
客戶端對接口請求作緩存。對於REST接口來講，若是某些接口實時性要求不高的狀況下，咱們可使
用max-age來指定一個小的緩存時間，這樣對客戶端和服務器端雙方都是有利的。通常來講只對GET
方法且返回200的狀況下使用緩存，在某些狀況下咱們也能夠對返回3xx或者4xx的狀況下作緩存，能夠防範錯誤訪問帶來的負載。
咱們能夠自定義一些頭信息，做爲客戶端和服務器間的通訊使用，但不能改變HTTP方法的性質。自
定義頭儘可能簡單明瞭，不要用body中的信息對其做補充說明。

API 地址和版本
在 url 中指定 API 的版本是個很好地作法。若是 API 變化比較大，能夠把 API 設計爲子域名，好比 https://api.github.com/v3；也能夠簡單地把版本放在路徑中，好比 https://example.com/api/v1。另外一種作法是，將版本號放在HTTP頭信息中。