RESTful

RESTful 是什么

RESTful是一种软件设计风格，全称是：Representational State Transfer（表现层状态转移/用URL定位资源，用HTTP动词描述操作） 有哪些RESTful风格的接口？ 可以参考Github API

why choose RESTful ？

接口基本原则：

1、安全可靠，高效易扩展

2、简单明了，可读性强，没有歧义

3、API风格统一，调用规则，传入参数和返回数据有统一的标准

RESTful的设计理念基于HTTP协议，设计原则：

1、HTTPS

HTTPS为接口的安全提供了保障，可以有效防止通信被窃听和篡改，可以通过 cerbot等工具。

Attention：非HTTPS的API调用，不要重定向到HTTPS。而要直接返回调用错误以禁止不安全的调用。

2、域名

应当尽可能的将API和主域名区分开，可以使用专用的域名：

https://api.zoe.com

Or

https://www.zoe.com/api

3、版本控制

第一种：将版本号直接加入到URL中

https://api.zoe.com/v1
https://api.zoe.com/v2

第二种：使用http请求头的accept字段进行区分（推荐）

Https://api.zoe.com/
Accept:application/prs.zoe.va+json
Accept:application/prs.zoe.va+json

4、用URL定位资源

在REST福利的架构中，所有的一切都表示资源，每个URL都代表一个资源（名词），而且大部分情况下资源是名词的复数，尽量不要在URL中出现动词。 Such as：(冒号开始的代表变量)

总结：

1、资源的设计可以嵌套，表明资源与资源之间的关系

2、大部分情况下访问的是某个资源集合，想要得到单个资源，可以通过资源的id或者number等唯一标识获取。

3、某些情况下，资源会是单数形式，例如某个项目某个issue的锁，每个issue只会有一把锁，所以是单数 错误的例子：

正确的例子:

5、用http动词描述操作

http设计了很多动词来表示不同的操作，RESTful吧这些利用的很好，来表明如何操作资源。

幂等性：指一次和多次请求某一个资源应该具有同样的副作用，也就是一次访问和多次访问，对这个资源带来的变化是相同的。

常见的动词及幂等性：

为什么PUT是幂等而patch不是呢？

因为put是根据客户端提供了完整的资源数据，客户端提交什么就更新什么，而patch有可能是根据客户端提供的参数，动态的计算出某个值，例如每次请求后资源的某个参数减1，所以多次调用，资源会有不同的变化。

Attention：GET请求对于资源来说是安全的，不允许GET请求改变（更新或创建）资源，但是实际中，为了方便统计类的数据，会有一些例外，例如帖子详情，记录访问次数，每调用一次，访问次数加一。

6、资源过滤

需要提供合理的参数供客户端过滤资源，such as：

7、正确使用状态码

8、数据响应格式

默认使用json作为数据响应格式，如果客户端需求使用其他的响应格式，例如xml，需要在accept头中指定需要的格式。

Https://api.zoe.com/
Accept:application/prs.zoe.v1+json
Accept:application/prs.zoe.v1+xml

对于错误数据，默认使用如下结构：

例如：

9、调用频率限制

为了防止服务器被攻击，减少服务器压力。需要对接口进行合适的限流控制，在响应头信息中加入合适的信息，告知客户端当前的限流情况：

超过限流次数后，需要返回 429 Too Many Requests 错误。

10、编写文档

为了方便用户使用，我们需要提供清晰的文档，尽可能包括以下几点

• 包括每个接口的请求参数，每个参数的类型限制，是否必填，可选的值等。

• 响应结果的例子说明，包括响应结果中，每个参数的释义。

• 对于某一类接口，需要有尽量详细的文字说明，比如针对一些特定场景，接口应该如何调用。

参考资料：

维基百科

阮一峰的日志-理解RESTful架构

REST in practice

end