对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就相当于给某个员工发放了一次工资,其实际的动作可能涉及到多张表的联动,如员工表的工资发放标志、工资发放记录表插入一条记录,公司财务表插入一条记录,操作日志表插入一条记录,系统消息表插入一条记录等……
对RESTful Web API的理解与设计思路相关推荐
- 我所理解的RESTful Web API [设计篇]
<我所理解的RESTful Web API [Web标准篇]>Web服务已经成为了异质系统之间的互联与集成的主要手段,在过去一段不短的时间里,Web服务几乎清一水地采用SOAP来构建.构建 ...
- 学习笔记-Spring Boot 开发 RESTful Web API(一)
题记: 本篇是Spring Boot 开发学习系列中基础知识学习的一部分,为 RESTful Web API 相关基础知识,为实践操作奠定理论基础. REST不是一个标准,而是一种软件应用架构风格.基 ...
- 如何实现RESTful Web API的身份验证
最近想拿一个小项目来试水RESTful Web API,项目只有几个调用,比较简单,但同样需要身份验证,如果是传统的网站的话,那不用说,肯定是用户名+密码在登录页获得登录Token,并把登录Token ...
- django restful 请求_利用 Django REST framework 构建 RESTful Web API
利用 Django REST framework 构建 RESTful Web API 终于到了动手操作的环节啦,这一节,我们以师生管理系统为例,带领大家搭建一套 framework Web API. ...
- 【视频教程】使用 ASP.NET Core 3.x 构建 RESTful Web API 已完结
使用 ASP.NET Core 3.x 构建 RESTful Web API 的视频教程已经完结,共50讲,约10.5小时. B站可看,点击原文链接. 度娘盘可下载完整视频: https://pan. ...
- 我所理解的RESTful Web API [Web标准篇]
REST不是一个标准,而是一种软件应用架构风格.基于SOAP的Web服务采用RPC架构,如果说RPC是一种面向操作的架构风格,而REST则是一种面向资源的架构风格.REST是目前业界更为推崇的构建新一 ...
- Web API核查表:设计、测试、发布API时需思考的43件事
当设计.测试或发布一个新的Web API时,你是在一个原有的复杂系统上构建新的系统.那么至少,你也要建立在HTTP上,而HTTP则是基于TCP/IP创建的.TCP/IP建立在一系列的管道上.当然,你也 ...
- 使用静态基类方案让 ASP.NET Core 实现遵循 HATEOAS Restful Web API
Hypermedia As The Engine Of Application State (HATEOAS) HATEOAS(Hypermedia as the engine of applicat ...
- 使用 Swagger UI 与 Swashbuckle 创建 RESTful Web API 帮助文件
作者:Sreekanth Mothukuru 2016年2月18日 本文旨在介绍如何使用常用的 Swagger 和 Swashbuckle 框架创建描述 Restful API 的交互界面,并为 AP ...
最新文章
- 如何通过 Impex 在 SAP Commerce Cloud 创建一个新的 Component
- 谈谈IP和MAC捆绑的破解之道
- 使用mongoose 在 Node中操作MongoDB数据库
- 看完这篇还不会kafka,我跪榴莲!
- 会议指南二维码生成_包装和准备技术会议的指南
- Linux常用命令大全(归类)
- 关于layui中lay-verify=required无效的解决办法
- java 本地文件路径怎么写_java本地文件路径怎么写
- 在c语言中怎么实现循环结构,浅议C语言中循环结构的教学方法.pdf
- SpringBoot + Vue 简单实现学生饭卡管理系统
- Python-Django框架学习笔记——第一课:Hello World
- 秦小明推荐书单+豆瓣金融TOP12 金融书籍
- python list diff_PythonList交集,并集,差集的应用
- 流氓软件与流氓系统的清理故事
- windows安装theano
- ctfshow命令执行篇
- c语言设计生命游戏,C语言实现生命游戏.doc
- Python 怎么利用Python绘制二元高次隐函数的函数图像及其极值点——以某双核论文模型方程为例
- 鲍尔默:Windows 8需求远超Windows 7
- 金蝶应收应付模块流程_金蝶KIS财务业务模块操作流程
热门文章
- OpenGL tessellatedcube棋盘格立方体的实例
- 将视频分成一帧一帧python_python ffmpeg任意提取视频帧的方法
- solidworks重建模型好慢_兄弟只能帮你到这了,SOLIDWORKS卡顿或许秘密就在这些选项里...
- [机器学习] ML重要概念:梯度(Gradient)与梯度下降法(Gradient Descent)
- 史上最简单的SpringCloud教程 | 第八篇: 消息总线(Spring Cloud Bus)
- dubbo控制中心部署,权重配置,以及管控台中各个配置的简单查看
- 项目中的一个AOP的编写案例(配置+案例)
- lisp求面与面的差集_AcGeVector3d是点阵的集合,通过等分点的差集得到。 新的点可以通过点与点阵相差得......
- Hourglass网络
- [C/C++] C++声明和定义的区别