对RESTful Web API的理解与设计思路

距离上一篇关于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就相当于给某个员工发放了一次工资，其实际的动作可能涉及到多张表的联动，如员工表的工资发放标志、工资发放记录表插入一条记录，公司财务表插入一条记录，操作日志表插入一条记录，系统消息表插入一条记录等……