开发者社区> 吞吞吐吐的> 正文

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

本文转自左正博客园博客,原文链接:http://www.cnblogs.com/soundcode/p/4040207.html,如需转载请自行联系原作者

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
如何设置阿里云服务器安全组?阿里云安全组规则详细解说
阿里云安全组设置详细图文教程(收藏起来) 阿里云服务器安全组设置规则分享,阿里云服务器安全组如何放行端口设置教程。阿里云会要求客户设置安全组,如果不设置,阿里云会指定默认的安全组。那么,这个安全组是什么呢?顾名思义,就是为了服务器安全设置的。安全组其实就是一个虚拟的防火墙,可以让用户从端口、IP的维度来筛选对应服务器的访问者,从而形成一个云上的安全域。
19808 0
阿里云服务器如何登录?阿里云服务器的三种登录方法
购买阿里云ECS云服务器后如何登录?场景不同,阿里云优惠总结大概有三种登录方式: 登录到ECS云服务器控制台 在ECS云服务器控制台用户可以更改密码、更换系.
29171 0
阿里云服务器安全组设置内网互通的方法
虽然0.0.0.0/0使用非常方便,但是发现很多同学使用它来做内网互通,这是有安全风险的,实例有可能会在经典网络被内网IP访问到。下面介绍一下四种安全的内网互联设置方法。 购买前请先:领取阿里云幸运券,有很多优惠,可到下文中领取。
22539 0
阿里云服务器ECS登录用户名是什么?系统不同默认账号也不同
阿里云服务器Windows系统默认用户名administrator,Linux镜像服务器用户名root
16454 0
阿里云服务器端口号设置
阿里云服务器初级使用者可能面临的问题之一. 使用tomcat或者其他服务器软件设置端口号后,比如 一些不是默认的, mysql的 3306, mssql的1433,有时候打不开网页, 原因是没有在ecs安全组去设置这个端口号. 解决: 点击ecs下网络和安全下的安全组 在弹出的安全组中,如果没有就新建安全组,然后点击配置规则 最后如上图点击添加...或快速创建.   have fun!  将编程看作是一门艺术,而不单单是个技术。
20700 0
阿里云服务器怎么设置密码?怎么停机?怎么重启服务器?
如果在创建实例时没有设置密码,或者密码丢失,您可以在控制台上重新设置实例的登录密码。本文仅描述如何在 ECS 管理控制台上修改实例登录密码。
23581 0
腾讯云服务器 设置ngxin + fastdfs +tomcat 开机自启动
在tomcat中新建一个可以启动的 .sh 脚本文件 /usr/local/tomcat7/bin/ export JAVA_HOME=/usr/local/java/jdk7 export PATH=$JAVA_HOME/bin/:$PATH export CLASSPATH=.
14900 0
4850
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
JS零基础入门教程(上册)
立即下载
性能优化方法论
立即下载
手把手学习日志服务SLS,云启实验室实战指南
立即下载