网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......)。
因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信。这导致API构架的流行,甚至出现"API First"的设计思想。
RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。
本文部分图文摘自于,https://www.jianshu.com/p/43dae0b83755
1. Rest来源:
REST:是一组架构约束条件和原则,REST是Roy Thomes Fielding在他2000年的博士论文中提出的。Roy Thomas Fielding是
HTTP协议(v1.0和v1.1)的主要设计者、Apache服务器作者之一、Apache基金会第一任主席。
2. 什么是REST
REST不是”rest”这个单词,而是几个单词的缩写 REpresentation State Transfer,直接翻译:表现层状态转移,这个翻译不太
好理解。网上找到一个比较通俗的说法是:URL定位资源,用HTTP动词(GET,POST,DELETE,PUSH等)描述操作
3. 什么是Restful
基于REST构建的API就是Restful风格。
近年随着移动互联网的发展,各种类型的客户端层出不穷,Restful可以通过一套统一的接口为PC、微信(H5)、IOS和Android提供服务,
这样的接口不需要前端样式,只提供数据。Restful架构如下:
4. 如何设计Restful风格的API
RestfulAPI就是由后台(SERVER端)来提供接口,前端来调用。前端调用API向后台发起HTTP请求,后台响应请求将处理结果反馈给前
端。也就是说Restful 是典型的基于HTTP的协议。那么RESTful API有哪些特征呢?
(1).Resource资源
首先是弄清楚资源的概念。资源就是网络上的一个实体、一段文本、一张图片或者一首歌曲。资源总是要通过一种载体来反应它的内容。
文本可以用TXT,也可以用HTML或者XML、图片可以用JPG格式或者PNG格式,JSON是现在最常用的资源表现形式。
(2).统一接口
Restful风格的数据元操作CRUD(create,read,update,delete)分别对应HTTP方法:GET用来获取资源,POST用来新建资源(也可
以用于更新资源),PUT用来更新资源,DELETE用来删除资源,这样就统一了数据操作的接口。
(3).使用HTTP状态码
当客户端通过API向服务器发出请求时,客户端应该知道反馈,无论是失败,成功还是请求错误。 HTTP状态代码是一系列标准化代码,
针对http请求的可能会发生的各种情况。 服务器应始终返回正确的状态代码。
很多人喜欢把错误信息放在返回值中,典型的Code和Message,其实比较Low。
下面是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表示服务器已关闭或无法接收和处理请求。大多数情况下,例如服务器正在进行维护。
(4).合理利用Http本身的方法
HTTP已定义了几组方法,这些方法指示要对资源执行什么类型的操作。我们制定web接口,要合理利用http的方法!URL是说白了,就是
一个句子,其中资源是名词,HTTP方法是动词。
GET 方法从资源请求数据,不应产生任何其他作用。
例如/schools/清华/students,返回所有清华大学的学生
POST方法请求服务器在数据库中创建资源,主要是在提交Web表单时。
/schools/清华/students/张三,在清华大学的学生资源,新增一个张三的学生。
POST是非幂等的,这意味着多个请求将具有不同的效果。
PUT方法请求服务器更新资源或创建资源(如果不存在)。
/schools/清华/students/张三, 对清华大学下的学生资源中,更新或者创建张三。
PUT是幂等的,这意味着多个请求将具有相同的效果。
DELETE方法请求从数据库中删除资源或其实例。
/schools/清华/students/张三,从清华大学的学生集合中,删除学生张三的资源。
(5).无状态
所谓无状态即所有的资源都可以URI定位,而且这个定位与其他资源无关,也不会因为其他资源的变化而变化。Restful 是典型的基于
HTTP的协议,HTTP连接最显著的特点是客户端发送的每次请求都需要服务器回送响应,在请求结束后,会主动释放连接。从建立连接到关闭
连接的过程称为“一次连接”。前面一次请求与后面一次请求没有必然的联系,所以是无状态的。
(6).使用JSON作为通信格式
JSON阅读性更高,扩展性更强,适合各种环境和语言进行解析,现在大的互联网公司,对外提供的API基本都使用JSON。
(7).搜索,排序,过滤和分页
所有这些操作都只是对一个数据集的查询。将不会有新的API集来处理这些操作。我们需要使用GET方法API附加查询参数。
下面看几个例子:
GET /schools ? search = 清华大学 在大学集合中,搜索清华大学
GET /schools ? sort = rank_asc 按照升序排列学校
GET /schools ? location = 北京 按照城市对学校过滤
GET /schools ? page=6 获取第六页的学校列表
(8).使用版本控制
例如下面两个版本地址:
http://api.yourservice.com/v1/schools/清华
http://api.yourservice.com/v2/schools/清华
在API上加入版本信息可以有效的使用户访问正确的API,v2是新开发功能,开发阶段,让所有用户访问v1,等开发完成统一切到v2。
可以有效的跨版本访问,例如在v2版本,还需要访问v1版本的一些接口