设计糟糕的 RESTful API 就是在浪费时间!
现在微服务真是火的一塌糊涂。大街小巷,逢人必谈微服务,各路大神纷纷忙着把自家的单体服务拆解成多个Web微小服务。而作为微服务之间通信的桥梁,Web API的设计就显得非常重要。
HTTP是目前互联网使用最多的协议,但是作为HTTP协议创始人之一的Roy Fielding认为,过去十年,大家都在错误地使用HTTP协议。删除一个数据,路径往往是 delete/{id},更新一条数据,路径往往被定义为update/{id}。你已经被Roy在心里默默的鄙视了!
Roy Fielding提出了一种用于设计Web服务的架构方法,称为Representational State Transfer(REST)。REST的概念是将API结构分离为操作和资源,使用HTTP方法GET、DELETE、POST和PUT操作资源。
设计糟糕的REST API = 浪费时间!优秀的API就像一位艺术家在舞台上表演,其用户就是观众,能给所有人带来赏心悦目的美感。
REST API里面的术语
Resource(资源)是指代表某种东西的对象,它具有一些与之相关的数据,并且可以有一组方法对其进行操作。例如,学校、班级和学生是资源,删除、添加、更新是要对这些资源执行的操作。
Collections(集合)是一组资源,例如,211大学是全国211所优质大学的集合。
URL(统一资源定位符)是可以通过其定位资源的路径,并且可以对其执行某些操作。
API设计使用名词,而不是动词
获取所有学生,可能通过如下API:/getAllStudents;
增加学生:/addNewStudent;
更新学生:/updateStudent;
删除学生:/deleteStudent;
删除所有学生:/deleteStudents;
获取三好学生:/getSanHaoStudents;
......
对于不同的操作,会衍生出越来越多的API接口,数量不停的增多,接口将会变得混乱和难以维护。
有没有感觉哪里不对?
URL应仅包含资源(名词)而不包含动作或者动词,增加学生的API路径:/addNewStudent,包含操作addNew以及资源名称Student。
那么正确的方法是什么?
/schools 是一个很好的例子,不包含任何动作。但是我们怎么告诉服务器,有关学校资源的操作呢?例如增加,删除或者更新学校?
这就是HTTP方法(GET,POST,DELETE,PUT)(也成为动词)发挥作用的地方。API接口的资源应始终为复数,如果我们要访问资源的一个实例,我们可以在URL中传递id或者name之类的。
GET 路径 /schools 获取所有的学校;
GET 路径 /schools/清华 获取名字叫清华大学的详细信息;
DELETE 路径 /schools/清华 从学校列表中,删除清华大学。
资源和资源之间也有可能有父子关系,那又应该如何设计?例如学校的学生,下面是一些示例:
GET /schools/清华/students 获取清华大学的所有学生;
GET /schools/清华/students/张三 获取清华大学名字叫张三的学生的详细信息;
DELETE /schools/清华/students/张三 删除清华大学名字叫张三的学生。
合理利用HTTP本身的方法
HTTP已定义了几组方法,这些方法指示要对资源执行什么类型的操作。我们制定Web接口,要合理利用HTTP的方法。
URL是说白了,就是一个句子,其中资源是名词,HTTP方法是动词。
- GET 方法从资源请求数据,不应产生任何其他作用。例如/schools/清华/students,返回所有清华大学的学生。
- POST方法请求服务器在数据库中创建资源,主要是在提交Web表单时。/schools/清华/students/张三,在清华大学的学生资源,新增一个张三的学生。POST是非幂等的,这意味着多个请求将具有不同的效果。
- PUT方法请求服务器更新资源或创建资源(如果不存在)。/schools/清华/students/张三, 对清华大学下的学生资源中,更新或者创建张三。PUT是幂等的,这意味着多个请求将具有相同的效果。
- DELETE方法请求从数据库中删除资源或其实例。/schools/清华/students/张三,从清华大学的学生集合中,删除学生张三的资源。
使用JSON作为通信格式
JSON阅读性更高,扩展性更强,适合各种环境和语言进行解析,现在大的互联网公司,对外提供的API基本都使用JSON。
使用HTTP状态码
当客户端通过API向服务器发出请求时,客户端应该知道反馈,无论是失败、成功还是请求错误。 HTTP状态代码是一系列标准化代码,针对HTTP请求的可能会发生的各种情况,而服务器应始终返回正确的状态代码。很多人喜欢把错误信息放在返回值中,典型的Code和Message,其实是不合理的。
下面是HTTP状态码,可以合理利用处理各种请求反馈,将HTTP自身的错误和服务器内部的错误,有一个很好的区分:
2xx(成功类别)
200 Ok表示GET,PUT或POST成功的标准HTTP响应。
201 Created每当创建新实例时,都应返回此状态代码。例如,使用POST方法创建新实例时,应始返回201状态代码。
204 No Content表示请求已成功处理,但未返回任何内容。
3xx(重定向类别)
304 Not Modified表示客户端已在其缓存中有响应,因此无需再次传输相同的数据。
4xx(客户端错误类别)
这些状态代码表示客户端已提出错误请求。
400 Bad Request表示未处理客户端的请求,因为服务器无法理解客户端要求的内容。
401 Unauthorized表示不允许客户端访问资源,并应使用所需凭据重新请求。
403 Forbidden表示请求有效且客户端已通过身份验证,但不允许客户端出于任何原因访问该页面或资源。例如,有时不允许授权客户端访问服务器上的目录。
404 Not Found表示请求的资源现在不可用。
410 Gone表示已移动的请求资源不再可用。
5xx(服务器错误类别)
500内部服务器错误表示请求有效,但服务器完全混淆,并要求服务器提供某些意外情况。
503 Service Unavailable大多数情况下表示服务器已关闭或无法接收和处理请求,例如服务器正在进行维护。
搜索、排序、过滤和分页
所有这些操作都只是对一个数据集的查询,将不会有新的API集来处理这些操作,我们需要使用GET方法API附加查询参数。
下面看几个例子:
GET /schools ? search = 清华大学 在大学集合中,搜索清华大学;
GET /schools ? sort = rank_asc 按照升序排列学校;
GET /schools ? location = 北京 按照城市对学校过滤;
GET /schools ? page=6 获取第六页的学校列表。
使用版本控制
例如下面两个版本地址:
http://api.yourservice.com/v1/schools/清华
http://api.yourservice.com/v2/schools/清华
在API上加入版本信息可以有效的使用户访问正确的API,v2是新开发功能,开发阶段让所有用户访问v1,等开发完成统一切到v2。这样可以有效地跨版本访问,例如在v2版本,还需要访问v1版本的一些接口。
总结
最后总结一下:
- API接口都用小写;
- 使用JSON通信;
- API带版本控制,比如v1、v2;
- 使用Token令牌进行鉴权;
- 路径中单词连接使用中划线-;
- 使用HTTP自身的方法表示增删改查资源, GET:查询,POST:新增,PUT:更新,DELETE:删除;
- 合理使用HTTP状态码,200,201,400,401,403,500。比如401表示用户身份认证失败,403表示验证身份通过了,但是无权限操作资源。
在此,祝大家都设计出优秀的Restful API!
设计糟糕的 RESTful API 就是在浪费时间!的更多相关文章
- 虚拟研讨会:如何设计好的RESTful API?
http://www.infoq.com/cn/articles/how-to-design-a-good-restful-api/ REST架构风格最初由Roy T. Fielding(HTTP/1 ...
- RESTful API 设计指南,RESTful API 设计最佳实践
RESTful API 设计指南,RESTful API 设计最佳实践 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). ...
- 虚拟研讨会:如何设计好的RESTful API(转)
原文:虚拟研讨会:如何设计好的RESTful API? REST架构风格最初由Roy T. Fielding(HTTP/1.1协议专家组负责人)在其2000年的博士学位论文中提出.HTTP就是该架构风 ...
- 如何设计好的RESTful API 之好的RESTful API 特征
原文地址:http://blog.csdn.net/ywk253100/article/details/25654021 导读:设计好RESTful API对于软件架构的可扩展性.可伸缩性和消费者的体 ...
- 如何设计好的RESTful API之安全性
保证RESTful API的安全性,主要包括三大方面: a) 对客户端做身份认证 b) 对敏感的数据做加密,并且防止篡改 c) 身份认证之后的授权 1.对客户端做身份认证,有几种常见的做法: 1)在请 ...
- 如何设计出优秀的Restful API?
https://mp.weixin.qq.com/s?__biz=MzU0OTE4MzYzMw==&mid=2247485240&idx=1&sn=b5b9c8c41659d2 ...
- (转载) RESTful API 设计指南
作者: 阮一峰 日期: 2014年5月22日 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). 因此,必须有一种统一的机制 ...
- RESTful API 设计指南
转自:http://www.ruanyifeng.com/blog/2014/05/restful_api.html 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机. ...
- RESTful API 设计指南 (转)
RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰 链接:http://www.ruanyifeng.com/blog/2014/0 ...
随机推荐
- Java位运算实现加减乘除四则运算
本文是继<一文了解有趣的位运算>的第二篇文章. 我们知道,计算机最基本的操作单元是字节(byte),一个字节由8个位(bit)组成,一个位只能存储一个0或1,其实也就是高低电平.无论多么复 ...
- ios 把数组对象转成json字符串存起来
1第一步是我们获取数据源 一般我们都是从接口请求数据 NSArray *subColumnsArray = nil; NSDictionary *dict = [NSJSONSerialization ...
- 几道STL题目(FJUT - OJ STL训练1)
这个OJ一直在做,一些专题题目都很好,从易至难,阶梯上升,很适合像我这样的蒟蒻 =7= 这篇是关于其中一个专题训练的题解思路及代码 http://120.78.128.11/Contest.jsp ...
- 理解setState
近来在学习react源码, 最初是直接从入口一行一行的看, 结果跟着调用的函数跳转来跳去头都晕了. 后来决定带着一个目的去看源码, 每次看只研究一个东西. 一开始最想了解的就是充满魔性的setStat ...
- Kubernetes Dashboard 终结者:KubeSphere
原文链接:Kubernetes Dashboard 终结者:KubeSphere 2018 年 7 月份,青云在 Cloud Insight 云计算峰会上推出了一款全新的容器平台--KubeSpher ...
- java数据结构——哈希表(HashTable)
哈希表提供了快速的插入操作和查找操作,每一个元素是一个key-value对,其基于数组来实现. 一.Java中HashMap与Hashtable的区别: HashMap可以接受null键值和值,而Ha ...
- vsftpd上传文件大小为0(主动模式)
最近在搞VSFTPD+Nginx结合,但是发现上传文件大小总是为0, 由于最开始在搞的时候不知道主动模式和被动模式到底是什么鬼东西,所以遇到问题根本找不到根的原因,遇到问题只是乱搜,好像是解决了问题, ...
- Google AppCrawler初探
AppCrawler是什么 你可以把它想成类似monkey一样的工具,调起你的应用程序并执行各种动作(点击,输入,滑动等)来通过这种方式 来查看各种情况下应用程序的状态 官方文档链接:AppCrawl ...
- 从原理到场景 系统讲解 PHP 缓存技术(全)
概述 缓存已经成了项目中是必不可少的一部分,它是提高性能最好的方式,例如减少网络I/O.减少磁盘I/O 等,使项目加载速度变的更快. 缓存可以是CPU缓存.内存缓存.硬盘缓存,不同的缓存查询速度也不一 ...
- javaweb中文中乱码分析与解决
要想解决乱码的问题, 最好的办法是先弄清楚javaweb中数据传送的原理. 本文件将简单的讲解客户端的请求和服务器响应中编码的转换过程, 以及如何解决乱码的 问题. request(req): se ...