距離上一篇關於Web API的文章（如何實現RESTful Web API的身份驗證）有好些時間了，在那篇文章中提到的方法是非常簡單而有效的，我在實際的項目中就這么用了，代碼經過一段時間的磨合，已經很穩定了，所以我打算寫篇總結，並在最近這段時間里提供一個ASP.net Web API的綜合例子。
對四個HTTP方法的理解
眾所周知，HTTP有四個方法，GET、POST、PUT和DELETE，分別對應數據庫的SELECT、INSERT、UPDATE和DELETE，一般的教程說到這里也就Over了，其實光是知道這個還不夠，還不足以把各種業務操作轉變為這四個方法。下面我給出一些設計思路，這是我自行實踐的總結，如有謬誤，請不吝指正：
GET
沒錯，就是SELECT，如果這個業務操作不會改變服務器的數據，那么就可以將它抽象成GET方法，但也不絕對，比如很多網站提供了文件下載，按理說下載應該是不會改變服務器數據的，所以用GET，但很多時候服務器還提供了下載計數，你說這算不算改變了服務器的數據？——這種情況一般不算，所以依然用GET。下面是GET方法的舉例：
- 獲取所有員工列表
- 按條件分頁查詢某些員工信息
- 獲取一個員工的信息
- 下載一個文件
- 獲取當前輸入的商品的價格
這么看來GET可是使用相當多的方法。
PUT
UPDATE一條記錄就抽象成PUT方法，那這個動作是不是也會用得很多呢？這個比你想像中的少得多，為什么？因為大量的修改記錄的動作都不只是一個簡單的UPDATE動作，比如用戶要撤銷一個訂單，這個操作表面上看起來是修改一條訂單記錄的狀態為“撤銷”，但實際上比這個要復雜得多，我們的訂貨是有流程的，用戶撤銷一個訂單其實只是向我們的服務器提出了一個撤銷訂單的請求，讓這個訂單轉入了撤銷流程，而不是簡單地修改訂單記錄的狀態，這里面有一連串的動作，比如：等待管理員確認，更新應收款信息，將已出庫的貨物重新入庫，寫操作日志，發送系統通知等等，所以這個動作應該是POST，而不是PUT，大多數涉及業務流程的東西都是POST，這個我后面會再提到，而PUT則用於簡單的，不涉及業務流程的數據庫單條記錄UPDATE，例如：
- 用戶修改自己的個人信息（假設這個修改動作不需要審批）
- 用戶編輯了一張暫存（未轉入執行流程）的訂單
POST
表面上看起來對應到數據庫的一次INSERT，但實際上對比PUT，POST的使用是廣泛很多的，可以說大多數業務操作都會被抽象成POST方法，例如：
- 新增一個用戶
- 提交一個訂單
- 撤銷一個訂單
- 付款
- 給員工發放工資
- 提交一個基礎資料的修改申請（需要審批）
- 激活一個產品
- 駁回一個員工的申請
想想看上述的這些動作往往涉及到數據庫的若干張表的一系列的變化，這個時候就不能簡單地使用PUT，而是應該使用POST，代表“提交了一個XX的請求”，理解這點很關鍵。
DELETE
對應SQL語句的DELETE，表示刪除一個對象，是不是應該使用也很多呢？其實跟PUT一樣，使用得比你想像的少，因為大多數時候，我們的數據庫所執行的“刪除”都不是簡單的DELETE，甚至大多數對象，我們都不會提供直接的刪除，例如用戶，為了保證數據的完整性，我們在數據庫中使用了許多的外鍵約束，要直接DELETE一條用戶記錄是不會成功的，我們只能“停用”一個用戶，表示此用戶不再生效。當然了，話不是那么絕對，如果這是個剛剛增加的用戶並且沒有在其它表中引用到它，那么確實可以直接把它DELETE掉，這種情況出現在管理員剛剛添加了一個用戶，但發現用戶名輸錯了，而用戶名卻是無法修改的，管理員只能嘗試刪除這個用戶然后重新添加，或者“停用”掉這個錯誤的用戶，只是這么一來會產生一條完全沒意義的用戶記錄。DELETE用於你認為需要提供DELETE方法的場合（很多時候其實不需要，這取決於你的設計），例如：
- 刪除一個用戶（很可能執行失敗）
- 刪除一條暫存的訂單（此訂單尚未轉入處理流程）
- 刪除一條系統消息
更具體的動作描述
為了表達得更具體些，我就把上面舉的這些例子轉變為具體化的URI及動作描述：
| 操作 | URI | HTTP方法 | 說明 |
| 獲取所有員工列表 | /api/emp/employees | GET | |
| 按條件分頁查詢某些員工信息 | /api/emp/employees?sex=m&page=1&numberperpage=20 | GET | 在URI中帶上參數 |
| 獲取一個員工的信息 | /api/emp/employees/58 | GET | 58是員工的ID，當然你也可以設計成用戶名 |
| 下載一個文件 | /api/fileservice/files/2832 | GET | 2832是文件的ID，當然你可以設計成文件名或者GUID |
| 獲取當前輸入的商品的價格 | /api/sale/goods/32680 | GET | 32680是商品的ID |
| 用戶修改自己的個人信息（假設這個修改動作不需要審批） | /api/admin/users/8642 | PUT | 8642是用戶的ID，另外要帶上修改所需要的各種信息 |
| 用戶編輯了一張暫存（未轉入執行流程）的訂單 | /api/sale/orders/234892 | PUT | 234892是訂單的ID，另外要帶上修改訂單所需的各種信息 |
| 新增一個用戶 | /api/admin/users | POST | 帶上新增用戶所需要的信息 |
| 提交一個訂單 | /api/sale/orders | POST | 帶上訂單完整信息 |
| 付款 | /api/sale/pay | POST | 付款完整信息，將包含要支付的訂單的ID等信息 |
| 給員工發放工資 | /api/emp/paysalary | POST | 帶上發放工資的完整信息，將包括員工ID，發放工資的月份和金額等 |
| 提交一個基礎資料的修改申請（需要審批） | /api/basic/modifymanufacture | POST | 帶上要修改的對象的完整信息，包括ID等 |
| 激活一個產品 | /api/sale/activateproduct | POST | 帶上要激活的產品的相關信息，包括ID等 |
| 駁回一個員工的申請 | /api/admin/approve | POST | 帶上申請ID、駁回原因等 |
| 刪除一個用戶（很可能執行失敗） | /api/admin/users/567 | DELETE | 567為要刪除的用戶的ID |
| 刪除一條暫存的訂單（此訂單尚未轉入處理流程） | /api/sale/orders/234892 | DELETE | 234892為訂單ID |
| 刪除一條系統消息 | /api/sys/messages/1008689021 | DELETE | 1008689021為系統消息的ID |
URI中的“api”是固定的，用於區別於普通的網頁的URI，接下去的“emp”、“fileservice”、“sale”、“admin”、“basic”和“sys”等可看作是分類，例如“給員工發放工資”和“員工信息”這兩個“資源”都是放在“emp”這個分類中的，剩余的部分是對象名稱，或稱資源名稱，其實准確地說，完整的URI地址才是真正的資源名稱，為什么叫資源？google一下RESTful Web API，看看RESTful的“R”就理解了，簡單地說，我們把各種操作都最終抽象為資源，一切業務操作（不管多復雜）都轉變為對某個資源的增刪查改，也就是上面提到的四個HTTP的方法。
GET、PUT和DELETE方法都比較顯而易見，好理解，大多數時候，這幾個方法的資源都確確實實對應着數據庫的某張表或某條記錄，例如“/api/admin/users”可能對應着數據庫中的ADMIN_USER表，而“/api/admin/users/8642”則對應着ADMIN_USER表中的ID為8642的這條用戶記錄。
POST方法則不是那么直截了當，例如“/api/emp/paysalary”，也許數據庫中根本就沒有一個直接與之一一對應的表，paysalary是一個抽象的業務操作對象，往這個對象執行一下POST就相當於給某個員工發放了一次工資，其實際的動作可能涉及到多張表的聯動，如員工表的工資發放標志、工資發放記錄表插入一條記錄，公司財務表插入一條記錄，操作日志表插入一條記錄，系統消息表插入一條記錄等……
這就是我對Web API的設計的理解，大家看看有什么問題？