restful api接口设计

技术由来：

互联网早期，页面请求和并发量不高，且移动端未盛行时对接口要求不高，使用动态页面(jsp)就能满足绝大多数的使用需求。但是随着互联网和移动设备的发展，人们对Web应用的使用需求也增加，传统的动态页面由于低效率而渐渐被HTML+JavaScript(Ajax)的前后端分离所取代，并且安卓、IOS、小程序等形式客户端层出不穷，客户端的种类出现多元化，而客户端和服务端就需要接口进行通信，但接口的规范性就又成了一个问题：

所以一套结构清晰、符合标准、易于理解、扩展方便让大部分人都能够理解接受的接口风格就显得越来越重要，而RESTful风格的接口(RESTful API)刚好有以上特点，就逐渐被实践应用而变得流行起来。

使用resetful设计的接口特点：看Url就知道要什么资源数据，看http method就知道进行什么操作！

所以RESTful API就是一套接口设计风格，用来规范多种形式的前端和同一个后台的交互方式。

使用场景：

前后端分离。前端拿到数据只负责展示和渲染，不对数据做任何处理。后端处理数据并以JSON格式传输出去，定义这样一套统一的接口，在web，ios，android三端都可以用相同的接口，节约开发成本以及便于同一调试。

区分REST和RESTful ：

REST是几个单词缩写 -- REpresentational State Transfer 直接翻译：表现层状态转移。字面理解太复杂了，先简单理解为：URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。

REST描述的是在网络中client和server的一种交互形式；REST并没有一个明确的标准，而更像是一种设计的风格，满足这种设计风格的程序或接口我们称之为RESTful(从单词字面来看就是一个形容词)。所以RESTful API 就是满足REST架构特征的接口。

REST架构特征和设计规范：

URI指向资源：使用URI = Universal Resource Identifier 统一资源标志符，用来标识抽象或物理资源的一个紧凑字符串。URI包括URL和URN，在这里更多时候可能代指URL(统一资源定位符)。RESTful是面向资源的，每种资源可能由一个或多个URI对应，但一个URI只指向一种资源。注意：使用名词的复数表示一个资源集合，如api.domain.com/users；使用斜线“/”用来表示资源之间的层次关系，如api.domain.com/users/1234/orders；URI 中应尽量使用小写字母，不实用下划线；URL末尾不应包含斜线“/”；

统一接口: 通过一定原则设计接口降低耦合，简化系统架构，这是RESTful设计的基本出发点。对资源的操作包括获取、创建、修改和删除，这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。换言而知，使用RESTful风格的接口但从接口上你可能只能定位其资源，但是无法知晓它具体进行了什么操作，需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断。具体的HTTP方法和方法含义如下图1，这样就统一了数据操作的接口。

非RESTful风格的API中，我们通常使用GET请求和POST请求完成增删改查以及其他操作，查询和删除一般使用GET方式请求，更新和插入一般使用POST请求。从请求方式上无法知道API具体是干嘛的，所有在URL上都会有操作的动词来表示API进行的动作，例如：query，add，update，delete等等。而RESTful风格的API则要求在URL上都以名词（推荐用复数）的方式出现，从几种请求方式上就可以看出想要进行的操作，这点与非RESTful风格的API形成鲜明对比。在谈及GET,POST,PUT,DELETE的时候，就必须提一下接口的安全性和幂等性，其中安全性是指方法不会修改资源状态，即读的为安全的，写的操作为非安全的。而幂等性的意思是操作一次和操作多次的最终效果相同，客户端重复调用也只返回同一个结果。

上述四个HTTP请求方法的安全性和幂等性如下：

举例子：说了这么多，到底RESTful长什么样子的呢？

GET:http://www.xxx.com/source/id 获取指定ID的某一类资源。
例如GET:http://www.xxx.com/friends/123表示获取ID为123的会员的好友列表。如果不加id就表示获取所有会员的好友列表。
POST:http://www.xxx.com/friends/123表示为指定ID为123的会员新增好友。其他的操作类似就不举例了。

如果一个操作无法对应到资源的某个操作上，此时可以适当地在URI中包含动词，但依然应该基于一个资源的标识符。例如：DELETE /users/1234/set-admin

无状态。服务器不能保存客户端的信息，每一次从客户端发送的请求中，要包含所有必须的状态信息，会话信息由客户端保存，服务器端根据这些状态信息来处理请求。当客户端可以切换到一个新状态的时候发送请求信息，当一个或者多个请求被发送之后, 客户端就处于一个状态变迁过程中。每一个应用的状态描述可以被客户端用来初始化下一次的状态变迁。

状态码和返回数据

服务端处理完成后客户端也可能不知道具体成功了还是失败了，服务器响应时，包含状态码和返回数据两个部分。

{  //响应格式status:0,data:{}||[],msg:’’
}

过滤信息：可以使用过滤信息进行筛选、搜索或分页查询等

可缓存性（Cacheability） ：服务端需回复是否可以缓存以让客户端甄别是否缓存提高效率。
版本号：可以将API的版本号放入URL。GET:http://www.xxx.com/v1/friend/123。或者将版本号放在HTTP头信息中。

总结：

RESTful风格的API 固然很好很规范，但大多数互联网公司并没有按照或者完全按照其规则来设计，因为REST是一种风格，而不是一种约束或规则，过于理想的RESTful API 会付出太多的成本。

比如RESTful API也有一些缺点

比如操作方式繁琐，RESTful API通常根据GET、POST、PUT、DELETE 来区分操作资源的动作，而HTTP Method 本身不可直接见，是隐藏的，而如果将动作放到URL的path上反而清晰可见，更利于团队的理解和交流。
并且有些浏览器对GET,POST之外的请求支持不太友好，还需要特殊额外的处理。
过分强调资源，而实际业务API可能有各种需求比较复杂，单单使用资源的增删改查可能并不能有效满足使用需求，强行使用RESTful风格API只会增加开发难度和成本。

所以，当你或你们的技术团队在设计API的时候，如果使用场景和REST风格很匹配，那么你们可以采用RESTful 风格API。但是如果业务需求和RESTful风格API不太匹配或者很麻烦，那也可以不用RESTful风格API或者可以借鉴一下，毕竟无论那种风格的API都是为了方便团队开发、协商以及管理，不能墨守成规。

参考学习文章：

https://www.toutiao.com/i6693727878158221836/

https://www.toutiao.com/a6902604637149692428/